npm package: @muhammedaksam/logo-objects-node
Description: TypeScript client SDK and tools for Logo Objects REST Service API
Author: Muhammed Mustafa AKŞAM
Latest version: 1.1.11

# Logo Objects REST API Client Node.js SDK

[![npm version](https://img.shields.io/npm/v/@muhammedaksam/logo-objects-node.svg)](https://www.npmjs.com/package/@muhammedaksam/logo-objects-node)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![CI](https://github.com/muhammedaksam/logo-objects-node/workflows/CI/badge.svg)](https://github.com/muhammedaksam/logo-objects-node/actions)
[![codecov](https://codecov.io/gh/muhammedaksam/logo-objects-node/branch/main/graph/badge.svg)](https://codecov.io/gh/muhammedaksam/logo-objects-node)
[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org/)

A comprehensive TypeScript client SDK for the Logo Objects REST Service API. This project provides type-safe API clients and comprehensive test suites.

## Features

- 🚀 **TypeScript Client SDK** - Type-safe API clients with full IntelliSense support
- 🧪 **Test Suites** - Comprehensive test coverage with Jest
- ⚡ **Performance Optimized** - Built-in retry logic, caching, and error handling

## Installation

Install the SDK using your preferred package manager:

```bash
pnpm add @muhammedaksam/logo-objects-node
```

Or with npm:

```bash
npm install @muhammedaksam/logo-objects-node
```

Or with yarn:

```bash
yarn add @muhammedaksam/logo-objects-node
```

## Quick Start

### Basic Usage

```typescript
import { LogoApiClient } from '@muhammedaksam/logo-objects-node';

// Initialize the client
const client = new LogoApiClient({
  baseURL: 'http://localhost:32001/api/v1',
  apiKey: 'your-api-key',
});

// Get employees
const employees = await client.employees.getAll({
  limit: 10,
  fields: 'CODE,NAME,E_MAIL',
});

// Get contacts
const contacts = await client.contacts.getAll({
  q: "NAME like 'John*'",
  limit: 20,
});

// Get sales orders
const salesOrders = await client.salesOrders.getByClientCode('CUST001');

// Get projects
const activeProjects = await client.projects.getActive();

// Create a new opportunity
const newOpportunity = await client.opportunities.create({
  CODE: 'OPP001',
  DESCRIPTION: 'New sales opportunity',
  CLIENTREF: 123,
  ESTVALUE: 50000,
});
```

### Advanced Usage with Query Options

```typescript
// Complex query with filtering and sorting
const filteredEmployees = await client.employees.getAll({
  q: "NAME like 'John*' and ACTIVE eq 1",
  sort: 'NAME,DATE_CREATED desc',
  expandLevel: 'full',
  withCount: true,
  limit: 25,
});

// Get employees with related data
const employeesWithDetails = await client.employees.getAll({
  expand: 'CONTACTS,ADDRESSES',
  fields: 'CODE,NAME,CONTACTS.EMAIL,ADDRESSES.CITY',
});
```

## Available Scripts

### Development

```bash
pnpm run dev              # Run development server
pnpm run build:watch      # Build in watch mode
```

### Testing

```bash
pnpm run test             # Run tests
pnpm run test:watch       # Run tests in watch mode
pnpm run test:coverage    # Run tests with coverage
pnpm run test:quick       # Quick validation test
pnpm run test:clients     # Comprehensive client test
pnpm run test:validate    # Run both validation tests
```

### Code Quality

```bash
pnpm run lint             # Run ESLint
pnpm run lint:fix         # Fix ESLint issues
```

### Utilities

```bash
pnpm run clean            # Clean build artifacts
```

## Supported APIs

This client supports all Logo Objects REST Service APIs

### Additional Features

- Advanced filtering and search capabilities
- Pagination and sorting options
- Field selection and data expansion
- Real-time data synchronization
- Comprehensive error handling

Each client provides specialized methods for common operations:

- CRUD operations (Create, Read, Update, Delete)
- Search and filtering by various criteria
- And much more...

## Configuration

### Client Configuration

```typescript
const client = new LogoApiClient({
  baseURL: 'http://localhost:32001/api/v1',
  apiKey: 'your-api-key',
  timeout: 30000, // Request timeout in ms
  retries: 3, // Number of retry attempts
  retryDelay: 1000, // Delay between retries in ms
});
```

## Error Handling

The client provides comprehensive error handling:

```typescript
try {
  const employee = await client.employees.getById(999);
} catch (error) {
  if (error instanceof ApiError) {
    console.log('API Error:', error.message);
    console.log('Status:', error.status);
    console.log('Code:', error.code);
  } else {
    console.log('Network Error:', error.message);
  }
}
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Development

This project uses [pnpm](https://pnpm.io/) for package management.

### Prerequisites

- Node.js 20 or higher
- pnpm 8.0.0 or higher

Install pnpm globally if you haven't already:

```bash
npm install -g pnpm
```

### Install Dependencies

```bash
pnpm install
```

### Build the Project

```bash
pnpm run build
```

### Development Setup

1. Install dependencies: `pnpm install`
2. Run tests: `pnpm test`
3. Start development server: `pnpm run dev`

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.