npm package: @naper/api-js-client
Description: A comprehensive TypeScript/JavaScript client library for interacting with the Naper API. This library provides a clean, type-safe interface for managing e-commerce data including products, categories, media, and more.
Author: Lucas Carvalho
Latest version: 0.1.22

# Naper API JavaScript Client

A comprehensive TypeScript/JavaScript client library for interacting with the Naper API. This library provides a clean, type-safe interface for managing e-commerce data including products, categories, media, and more.

## Installation

Install the package using npm:

```bash
npm install @naper/api-js-client
```

## Quick Start

### Basic Setup

```typescript
import axios from 'axios';
import { NaperClient, AxiosClient, Service } from '@naper/api-js-client';

// Create an Axios instance with your API configuration
const axiosInstance = axios.create({
  baseURL: 'https://yourstore.naper.ai',
  headers: {
    'Authorization': 'Bearer your-api-token',
    // Add other headers as needed
  }
});

// Create the HTTP client
const httpClient = new AxiosClient(axiosInstance);

// Create the Naper client
const naperClient = new NaperClient(httpClient);

// Create the service with all API endpoints
const api = new Service(naperClient);
```

### With Context

You can set a context (edit/view) for your API calls:

```typescript
// Use with edit context
const editApi = api.withContext('edit');

// Use with view context
const viewApi = api.withContext('view');
```

## API Reference

The library provides access to the following API endpoints:

### Products

```typescript
// Get products with query parameters
const products = await api.products.get({
  page: 1,
  per_page: 10,
  search: 'laptop'
});

// Create a new product
const newProduct = await api.products.post({
  name: 'New Product',
  type: 'simple',
  regular_price: '29.99',
  description: 'Product description'
});

// Get a single product
const product = await api.products.single.get(123);

// Update a product
const updatedProduct = await api.products.single.put({
  id: 123,
  name: 'Updated Product Name',
  regular_price: '39.99'
});

// Delete a product
await api.products.single.delete(123);

// Batch operations
const batchResult = await api.products.batch({
  create: [
    { name: 'Product 1', type: 'simple', regular_price: '19.99' },
    { name: 'Product 2', type: 'simple', regular_price: '29.99' }
  ],
  update: [
    { id: 1, name: 'Updated Product 1' }
  ]
});
```

### Product Variations

```typescript
// Get variations for a product
const variations = await api.products.single.variations(123).get();

// Create a new variation
const newVariation = await api.products.single.variations(123).post({
  regular_price: '25.99',
  attributes: [
    { name: 'Color', option: 'Red' }
  ]
});

// Update a variation
const updatedVariation = await api.products.single.variations(123).single.put({
  id: 456,
  regular_price: '27.99'
});
```

### Product Categories

```typescript
// Get product categories
const categories = await api.products.categories.get({
  page: 1,
  per_page: 20
});

// Create a new category
const newCategory = await api.products.categories.post({
  name: 'Electronics',
  slug: 'electronics'
});

// Get category tree
const categoryTree = await api.products.categories.tree({
  hide_empty: true
});
```

### Product Attributes

```typescript
// Get product attributes
const attributes = await api.products.attributes.get({
  page: 1,
  per_page: 10
});

// Create a new attribute
const newAttribute = await api.products.attributes.post({
  name: 'Color',
  slug: 'color',
  type: 'select'
});

// Get attribute terms
const terms = await api.products.attributes.single.terms(1).get({
  page: 1,
  per_page: 10
});

// Create a new attribute term
const newTerm = await api.products.attributes.single.terms(1).post({
  name: 'Red',
  slug: 'red'
});
```

### Media

```typescript
// Get media files
const mediaFiles = await api.media.get({
  page: 1,
  per_page: 20
});

// Upload a new media file
const formData = new FormData();
formData.append('file', fileBlob, 'image.jpg');
const uploadedMedia = await api.media.upload(formData);

// Get a single media file
const mediaFile = await api.media.single.get(123);

// Delete a media file
await api.media.single.delete(123);
```

### Users

```typescript
// Get users
const users = await api.users.get({
  page: 1,
  per_page: 10,
  role: 'customer'
});

// Create a new user
const newUser = await api.users.post({
  email: 'user@example.com',
  username: 'newuser',
  password: 'securepassword',
  role: 'customer'
});

// Get current user
const currentUser = await api.users.me();

// Update user
const updatedUser = await api.users.single.put({
  id: 123,
  first_name: 'John',
  last_name: 'Doe'
});
```

### Posts

```typescript
// Get posts by type
const posts = api.posts('blog');
const blogPosts = await posts.get({
  page: 1,
  per_page: 10,
  status: 'publish'
});

// Create a new post
const newPost = await posts.post({
  title: 'New Blog Post',
  content: 'Post content here',
  status: 'draft'
});
```

### Stores

```typescript
// Get stores
const stores = await api.stores.get({
  page: 1,
  per_page: 10
});

// Get a single store
const store = await api.stores.single.get(123);
```

### Settings

```typescript
// Get settings
const settings = await api.settings.get();

// Update settings
const updatedSettings = await api.settings.put({
  site_title: 'My Store',
  site_description: 'Best products online'
});
```

### Integrations

```typescript
// Get integrations
const integrations = await api.integrations.get({
  page: 1,
  per_page: 10
});

// Create a new integration
const newIntegration = await api.integrations.post({
  name: 'Custom Integration',
  type: 'webhook',
  config: {
    url: 'https://example.com/webhook'
  }
});
```

### Drafts

```typescript
// Get drafts
const drafts = await api.drafts.get({
  page: 1,
  per_page: 10
});

// Create a new draft
const newDraft = await api.drafts.post({
  title: 'Draft Title',
  content: 'Draft content'
});
```

### Queue

```typescript
// Get queue items
const queueItems = await api.queue.get({
  page: 1,
  per_page: 10,
  status: 'pending'
});

// Create a new queue item
const newQueueItem = await api.queue.post({
  type: 'process_order',
  data: {
    order_id: 123
  }
});

// Process queue item
await api.queue.single.process(456);
```

### Taxonomies

```typescript
// Get taxonomies
const taxonomies = await api.taxonomies.get({
  page: 1,
  per_page: 10
});

// Get terms for a specific taxonomy
const terms = api.terms('product_category');
const categoryTerms = await terms.get({
  page: 1,
  per_page: 20
});
```

### Data Center

```typescript
// Get data center information
const dataCenterInfo = await api.dataCenter.get();

// Get data center stats
const stats = await api.dataCenter.stats();

// Export data
const exportResult = await api.dataCenter.export({
  type: 'products',
  format: 'csv'
});
```

## Response Format

All API responses follow a consistent format:

```typescript
interface Response<T> {
  status: number;
  headers: Headers;
  data: T;
  isCollection: boolean;
  total: number | null;
}
```

Example response:
```typescript
{
  status: 200,
  headers: { 'content-type': 'application/json' },
  data: [...], // Your actual data
  isCollection: true,
  total: 150
}
```

## Error Handling

The library uses the underlying HTTP client (Axios) for error handling. You can catch and handle errors as follows:

```typescript
try {
  const products = await api.products.get({ page: 1 });
  console.log(products.data);
} catch (error) {
  if (error.response) {
    // Server responded with error status
    console.error('API Error:', error.response.status, error.response.data);
  } else if (error.request) {
    // Request was made but no response received
    console.error('Network Error:', error.request);
  } else {
    // Something else happened
    console.error('Error:', error.message);
  }
}
```

## TypeScript Support

This library is written in TypeScript and provides full type safety. All API methods are properly typed with request and response interfaces.

```typescript
import type { Product, CreateProduct, ProductsQuery } from '@naper/api-js-client';

// TypeScript will provide autocomplete and type checking
const product: Product = await api.products.single.get(123);
```

## Requirements

- Node.js >= 20.0.0
- TypeScript >= 5.0.0 (if using TypeScript)
- Axios >= 1.7.0 (peer dependency)

## 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

## License

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

## Support

For support, please open an issue on the [GitHub repository](https://github.com/Naper-AI/api-js-client) or contact the development team.