@ritas-inc/sapb1commandapi-client/CHANGELOG.md

A stateless TypeScript client for SAP B1 Service Layer Command API with comprehensive error handling, type safety, and batch operations

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.5.0] - 2025-01-11

### Added

- **Idempotency Support**: All mutating operations (POST, PATCH, DELETE) now support optional idempotency keys
  - Added `idempotencyKey` parameter to all 26 mutating methods across Plans, WorkOrders, Tags, and ProductionEntries services
  - Keys must be valid UUID format (v1-v5) to match API requirements
  - Server caches successful responses for 24 hours
  - Duplicate requests with same key return cached response (no duplicate operations)
- **Utility Functions**:
  - `generateIdempotencyKey()`: Generates a new UUID v4 for use as idempotency key
  - `isValidIdempotencyKey(key)`: Validates if a string is a valid UUID format
- **Documentation**: Comprehensive idempotency documentation in README with:
  - Usage examples and best practices
  - Error response formats (400 for invalid UUID, 409 for concurrent requests)
  - Complete list of all 26 supported operations

### Changed

- HTTPClient methods (`post`, `patch`, `delete`) now accept optional `idempotencyKey` parameter
- All service methods maintain backward compatibility - idempotency key is optional

### Technical Details

**Supported Operations with Idempotency**:

- **Plans** (5 methods): `create`, `updateStatus`, `updateProducts`, `updateReleaseDate`, `cancel`
- **Work Orders** (8 methods): `create`, `release`, `cancel`, `close`, + 4 batch operations
- **Tags** (8 methods): `create`, `activate`, `quantify`, `discard`, `clone`, `clear`, `createMultiple`, `batch.create`
- **Production Entries** (1 method): `create`

**Usage Example**:
```typescript
import { SAPB1CommandClient, generateIdempotencyKey } from '@ritas-inc/sapb1commandapi-client';

const client = new SAPB1CommandClient({ baseUrl: 'https://api.example.com' });
const idempotencyKey = generateIdempotencyKey();

// First request creates the resource
const response = await client.plans.create(
  userId, user, products, null, null, idempotencyKey
);

// Retry with same key returns cached response (no duplicate created)
const retryResponse = await client.plans.create(
  userId, user, products, null, null, idempotencyKey
);
```

## [1.1.0] - 2025-01-08

### Breaking Changes

- **Response Structure**: All API responses now follow a consistent success/error pattern
  - Success responses: `{ success: true, data: T, metadata?: any }`
  - Error responses: `{ success: false, problem: { ... } }`
- **Type System**: Types are now derived from Zod schemas instead of separate type files
- **Import Paths**: Types are now exported from the main module instead of subpaths

### Added

- Consistent API response structure across all endpoints
- RFC 7807 Problem Details format for error responses
- `isErrorResponse` helper function for type-safe error checking
- Response metadata support for additional context information
- Comprehensive TypeScript types derived from Zod schemas
- Better error context with request and response details

### Changed

- Authentication response now includes optional metadata with CompanyDB and UserName
- All service methods now return the full response object instead of just data
- Error responses are now part of the normal response flow (not thrown)
- Types are now generated from Zod schemas for better runtime validation
- Build process no longer generates source maps by default

### Removed

- Separate type definition files (now generated from schemas)
- Direct data access pattern (replaced with response.data)
- Source map generation for production builds

### Migration Guide

#### Response Handling

Before (v1.0.x):
```typescript
const { userId } = await client.auth.login(credentials);
const plan = await client.plans.create(userId, user, products);
```

After (v1.1.0):
```typescript
const authResponse = await client.auth.login(credentials);
if (authResponse.success) {
  const userId = authResponse.data.userId;
  
  const planResponse = await client.plans.create(userId, user, products);
  if (planResponse.success) {
    console.log(`Plan ID: ${planResponse.data.planId}`);
  }
}
```

#### Error Handling

Before (v1.0.x):
```typescript
try {
  const plan = await client.plans.create(userId, user, products);
} catch (error) {
  console.error(error.message);
}
```

After (v1.1.0):
```typescript
const response = await client.plans.create(userId, user, products);
if (!response.success) {
  console.error(response.problem.detail);
  console.error(response.problem.issues);
}
```

#### Type Imports

Before (v1.0.x):
```typescript
import type { AuthRequest } from '@ritas-inc/sapb1commandapi-client/types';
```

After (v1.1.0):
```typescript
import type { AuthRequest } from '@ritas-inc/sapb1commandapi-client';
```

## [1.0.2] - 2024-12-15

### Fixed
- Batch operation error handling improvements
- Network retry logic for transient failures

## [1.0.1] - 2024-12-10

### Fixed
- TypeScript declaration file paths
- ESM module resolution issues

## [1.0.0] - 2024-12-01

### Added
- Initial release
- Authentication service with SAP B1 login
- Plans management (create, update status, update products, cancel)
- Work orders management (create, release, cancel)
- Batch operations for work orders
- Automatic retry logic with exponential backoff
- Comprehensive TypeScript support
- Stateless client design
- Health check endpoint