🌟 Amazora Nexus - Modern, secure Amazon SP-API client for Node.js with TypeScript support
npm install amazora-nexusA modern, secure, and comprehensive Node.js client for Amazon Selling Partner API (SP-API) with full TypeScript support.
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.
- 🔒 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
``bash`
npm install amazora-nexus
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
`typescript
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);
}
}
`
`typescript
// 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',
},
});
`
`typescript
// 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);
`
`typescript
// 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,
});
`
`typescript
// 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'],
});
`
Create a .env file with your credentials:
`envAWS Credentials
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1
$3
typescript
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
typescript
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:
typescript
// 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:
typescript
// 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:
typescript
// 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:
typescript
import {
Order,
OrderItem,
InventorySummary,
CatalogItem,
SPAPIResponse
} from 'amazora-nexus';// Type-safe responses
const orders: SPAPIResponse<{ orders: Order[] }> = await amazora.orders.getOrders({
marketplaceIds: ['ATVPDKIKX0DER'],
});
``1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
MIT License - see LICENSE file for details.
- 📖 Documentation
- 🐛 Issues
- 💬 Discussions
See CHANGELOG.md for version history.
---
⚠️ Remember: Keep your credentials secure and never expose them to client-side code!