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:

npm install @naper/api-js-client

Quick Start

Basic Setup

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:

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

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

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

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

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

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

// 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: '[email protected]',
  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

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

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

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

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

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

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

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

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

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

Example response:

{
  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:

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.

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 file for details.

Support

For support, please open an issue on the GitHub repository or contact the development team.