@leancodepl/cqrs-client-base/README.md

Base types and interfaces for CQRS client implementations

# @leancodepl/cqrs-client-base

Base types and interfaces for CQRS clients.

## Installation

```bash
npm install @leancodepl/cqrs-client-base
# or
yarn add @leancodepl/cqrs-client-base
```

## API

### `TokenProvider`

Interface for token providers used in CQRS clients.

**Properties:**

- `getToken: () => Promise<string | undefined>` - Returns authentication token
- `invalidateToken: () => Promise<boolean>` - Invalidates and refreshes token

### `ValidationError<TErrorCodes>`

Represents validation errors from commands.

**Properties:**

- `PropertyName: string` - Property that failed validation
- `ErrorMessage: string` - Human-readable error message
- `ErrorCode: TErrorCodes[keyof TErrorCodes]` - Error code from provided map

### `CommandResult<TErrorCodes>`

Union type for command results.

**Types:**

- `SuccessfulCommandResult` - When command succeeds
- `FailedCommandResult<TErrorCodes>` - When command fails with validation errors

### `ApiResponse<TResult>`

Union type for API responses.

**Types:**

- `ApiSuccess<TResult>` - Successful response with result
- `ApiError` - Error response

## Usage Examples

### Token Provider Implementation

```typescript
import { TokenProvider } from "@leancodepl/cqrs-client-base"

const tokenProvider: TokenProvider = {
  getToken: async () => {
    return localStorage.getItem("authToken")
  },
  invalidateToken: async () => {
    localStorage.removeItem("authToken")
    return true
  },
}
```

### Command Error Handling

```typescript
import { CommandResult, ValidationError } from "@leancodepl/cqrs-client-base"

interface UserErrorCodes {
  EmailExists: 1
  InvalidEmail: 2
}

function handleCommandResult(result: CommandResult<UserErrorCodes>) {
  if (result.WasSuccessful) {
    console.log("Command succeeded")
  } else {
    result.ValidationErrors.forEach((error: ValidationError<UserErrorCodes>) => {
      console.log(`${error.PropertyName}: ${error.ErrorMessage}`)
    })
  }
}
```

### API Response Handling

```typescript
import { ApiResponse } from "@leancodepl/cqrs-client-base"

function handleApiResponse<T>(response: ApiResponse<T>) {
  if (response.isSuccess) {
    return response.result
  } else {
    throw new Error("API call failed")
  }
}
```