Amazora Nexus 🌟

A modern, secure, and comprehensive Node.js client for Amazon Selling Partner API (SP-API) with full TypeScript support.

⚠️ Security Notice

This package is designed for SERVER-SIDE use only. Never expose AWS credentials, access tokens, or any sensitive data to client-side code. Always keep your credentials secure and use environment variables.

Features

• 🔒 Secure: Server-side only, never exposes credentials
• 🚀 Modern: Built with TypeScript and modern Node.js features
• 📦 Comprehensive: Full coverage of SP-API endpoints
• 🔄 Simple: Clean, minimal implementation without external dependencies
• 📊 Rate Limiting: Automatic rate limit handling
• 🎯 Type Safe: Full TypeScript definitions for all API responses
• 🔧 Flexible: Easy to extend and customize
• 📚 Well Documented: Comprehensive documentation and examples

Installation

npm install amazora-nexus

Authentication

AmazoraNexus uses a simplified authentication approach that matches your existing working implementation:

• Endpoint: https://api.amazon.com/auth/O2/token
• Method: Direct refresh token flow using axios and qs
• No External Dependencies: Only uses core packages (axios, qs, aws4)
• Automatic Token Management: Handles token caching and refresh automatically

Quick Start

import { AmazoraNexus, SPAPIConfig } from 'amazora-nexus';

// Configure your SP-API credentials
const config: SPAPIConfig = {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  region: 'us-east-1',
  refreshToken: process.env.AMAZON_REFRESH_TOKEN!,
  clientId: process.env.AMAZON_CLIENT_ID!,
  clientSecret: process.env.AMAZON_CLIENT_SECRET!,
  marketplaceId: 'ATVPDKIKX0DER', // US marketplace
};

// Create client instance
const amazora = new AmazoraNexus(config);

// Use the API
async function example() {
  try {
    // Get orders
    const orders = await amazora.orders.getOrders({
      marketplaceIds: ['ATVPDKIKX0DER'],
      createdAfter: '2024-01-01T00:00:00Z',
    });
    
    console.log('Orders:', orders.data.orders);
    
    // Get inventory
    const inventory = await amazora.fbaInventory.getInventorySummaries({
      marketplaceIds: ['ATVPDKIKX0DER'],
      granularityType: 'Marketplace',
      granularityId: 'ATVPDKIKX0DER',
      details: true,
    });
    
    console.log('Inventory:', inventory.data.inventorySummaries);
    
  } catch (error) {
    console.error('SP-API Error:', error);
  }
}

API Modules

Orders API

// Get orders
const orders = await amazora.orders.getOrders({
  marketplaceIds: ['ATVPDKIKX0DER'],
  createdAfter: '2024-01-01T00:00:00Z',
  orderStatuses: ['Unshipped', 'PartiallyShipped'],
});

// Get order details
const order = await amazora.orders.getOrder('ORDER_ID');

// Get order items
const orderItems = await amazora.orders.getOrderItems('ORDER_ID');

// Update shipment status
await amazora.orders.updateShipmentStatus('ORDER_ID', {
  packageDetail: {
    packageReferenceId: 'REF_123',
    carrierCode: 'UPS',
    trackingNumber: '1Z999AA1234567890',
    shipDate: '2024-01-15T10:00:00Z',
  },
});

Reports API

// Create a report
const report = await amazora.reports.createReport({
  reportType: 'GET_MERCHANT_LISTINGS_ALL_DATA',
  marketplaceIds: ['ATVPDKIKX0DER'],
});

// Wait for report completion and get content
const reportContent = await amazora.reports.getReportContent(report.data.reportId);

// Parse CSV report
const csvData = await amazora.reports.parseCSVReport(report.data.reportId);

// Parse TSV report
const tsvData = await amazora.reports.parseTSVReport(report.data.reportId);

FBA Inventory API

// Get inventory summaries
const inventory = await amazora.fbaInventory.getInventorySummaries({
  marketplaceIds: ['ATVPDKIKX0DER'],
  granularityType: 'Marketplace',
  granularityId: 'ATVPDKIKX0DER',
  details: true,
});

// Get inventory for specific SKU
const skuInventory = await amazora.fbaInventory.getInventoryDetails('SKU_123', {
  marketplaceIds: ['ATVPDKIKX0DER'],
  granularityType: 'SellerSKU',
  details: true,
});

Catalog API

// Get catalog item by ASIN
const item = await amazora.catalog.getCatalogItem('B08N5WRWNW', {
  marketplaceIds: ['ATVPDKIKX0DER'],
  includedData: ['attributes', 'summaries'],
});

// Search catalog items
const searchResults = await amazora.catalog.searchCatalogItems({
  keywords: ['laptop'],
  marketplaceIds: ['ATVPDKIKX0DER'],
  includedData: ['summaries'],
});

Configuration

Environment Variables

Create a .env file with your credentials:

# AWS Credentials
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1

# Amazon SP-API Credentials
AMAZON_REFRESH_TOKEN=your_refresh_token
AMAZON_CLIENT_ID=your_client_id
AMAZON_CLIENT_SECRET=your_client_secret

# Marketplace
MARKETPLACE_ID=ATVPDKIKX0DER

Advanced Configuration

const config: SPAPIConfig = {
  // Required
  accessKeyId: 'your_access_key',
  secretAccessKey: 'your_secret_key',
  region: 'us-east-1',
  refreshToken: 'your_refresh_token',
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  marketplaceId: 'ATVPDKIKX0DER',
  
  // Optional
  baseUrl: 'https://sellingpartnerapi-na.amazon.com',
  timeout: 30000,
  retry: {
    retries: 3,
    retryDelay: 1000,
    retryMultiplier: 2,
  },
};

Error Handling

try {
  const orders = await amazora.orders.getOrders({
    marketplaceIds: ['ATVPDKIKX0DER'],
  });
} catch (error) {
  if (error instanceof SPAPIError) {
    console.error('SP-API Error:', {
      code: error.code,
      message: error.message,
      statusCode: error.statusCode,
      requestId: error.requestId,
    });
  } else {
    console.error('Unexpected error:', error);
  }
}

Rate Limiting

The client automatically handles rate limiting:

// Check current rate limit status
const rateLimitInfo = amazora.getRateLimitInfo();
if (rateLimitInfo) {
  console.log(`Remaining requests: ${rateLimitInfo.remaining}`);
  console.log(`Reset time: ${rateLimitInfo.resetTime}`);
}

Authentication

The client automatically handles LWA token refresh:

// Check if authenticated
if (amazora.isAuthenticated()) {
  console.log('Client is authenticated');
}

// Force refresh token
await amazora.refreshAuth();

Custom Requests

For endpoints not covered by the modules:

// Direct API calls
const response = await amazora.get('/custom/endpoint', {
  param1: 'value1',
  param2: 'value2',
});

const postResponse = await amazora.post('/custom/endpoint', {
  data: 'value',
});

TypeScript Support

Full TypeScript definitions are included:

import { 
  Order, 
  OrderItem, 
  InventorySummary, 
  CatalogItem,
  SPAPIResponse 
} from 'amazora-nexus';

// Type-safe responses
const orders: SPAPIResponse<{ orders: Order[] }> = await amazora.orders.getOrders({
  marketplaceIds: ['ATVPDKIKX0DER'],
});

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

Changelog

See CHANGELOG.md for version history.

⚠️ Remember: Keep your credentials secure and never expose them to client-side code!