@congminh1254/shopee-sdk/README.md

Shopee SDK maintaining by community

# Shopee SDK

[![CI](https://github.com/congminh1254/shopee-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/congminh1254/shopee-sdk/actions/workflows/ci.yml)
[![Coverage Status](https://coveralls.io/repos/github/congminh1254/shopee-sdk/badge.svg?branch=main)](https://coveralls.io/github/congminh1254/shopee-sdk?branch=main)
[![npm version](https://badge.fury.io/js/@congminh1254%2Fshopee-sdk.svg)](https://badge.fury.io/js/@congminh1254%2Fshopee-sdk)
[![Node.js Version](https://img.shields.io/node/v/@congminh1254/shopee-sdk.svg)](https://www.npmjs.com/package/@congminh1254/shopee-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

🎉 **The most complete, production-ready TypeScript SDK for Shopee Open API** 🎉

<a href="https://www.buymeacoffee.com/congminh1254" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me a Coffee" style="height: 40px !important;width: 150px !important;" ></a>

Build powerful Shopee integrations with confidence using our fully-featured SDK that covers **100% of Shopee's API endpoints**. Trusted by developers, built by the community.

## 📚 Documentation

**[Complete Documentation](./docs/README.md)** - Comprehensive guides and API references

### Quick Links

**Getting Started:**
- [Setup Guide](./docs/guides/setup.md) - Installation and configuration
- [Authentication](./docs/guides/authentication.md) - OAuth flow and token management
- [Token Storage](./docs/guides/token-storage.md) - Managing access tokens
- [Proxy Configuration](./docs/guides/proxy.md) - Using HTTP/HTTPS proxies

**API Managers:**
- [AuthManager](./docs/managers/auth.md) - Authentication operations
- [ProductManager](./docs/managers/product.md) - Product catalog management
- [OrderManager](./docs/managers/order.md) - Order processing
- [LogisticsManager](./docs/managers/logistics.md) - Shipping operations
- [PaymentManager](./docs/managers/payment.md) - Payment information
- [VoucherManager](./docs/managers/voucher.md) - Discount management
- [PushManager](./docs/managers/push.md) - Webhooks and notifications
- [PublicManager](./docs/managers/public.md) - Public API endpoints
- [AdsManager](./docs/managers/ads.md) - Advertising campaigns
- [AmsManager](./docs/managers/ams.md) - Affiliate Marketing Solutions (AMS)
- [AccountHealthManager](./docs/managers/account-health.md) - Performance metrics
- [ShopManager](./docs/managers/shop.md) - Shop information and settings
- [MediaManager](./docs/managers/media.md) - Image and video upload
- [MediaSpaceManager](./docs/managers/media-space.md) - Media uploads (images and videos)
- [MerchantManager](./docs/managers/merchant.md) - Merchant information and warehouses
- [GlobalProductManager](./docs/managers/global-product.md) - Global product management
- [FirstMileManager](./docs/managers/first-mile.md) - First mile logistics
- [DiscountManager](./docs/managers/discount.md) - Discount campaigns
- [BundleDealManager](./docs/managers/bundle-deal.md) - Bundle deal promotions
- [AddOnDealManager](./docs/managers/add-on-deal.md) - Add-on deal promotions
- [ShopFlashSaleManager](./docs/managers/shop-flash-sale.md) - Flash sale campaigns
- [FollowPrizeManager](./docs/managers/follow-prize.md) - Follow prize activities
- [TopPicksManager](./docs/managers/top-picks.md) - Top picks collections
- [ShopCategoryManager](./docs/managers/shop-category.md) - Shop category management
- [ReturnsManager](./docs/managers/returns.md) - Return and refund management
- [SbsManager](./docs/managers/sbs.md) - Shopee Business Services (SBS) warehouse inventory
- [FbsManager](./docs/managers/fbs.md) - Fulfillment by Shopee operations
- [LivestreamManager](./docs/managers/livestream.md) - Live streaming features
- [VideoManager](./docs/managers/video.md) - Shopee Video features and analytics

## Installation

```bash
npm install @congminh1254/shopee-sdk
```

**Requirements:** Node.js >= 20.0.0

### What You Get
✅ Complete TypeScript definitions for all 29 API managers  
✅ Automatic token refresh and management  
✅ Built-in error handling and retry logic  
✅ Zero dependencies (except node-fetch)  
✅ Full documentation and examples  

## Quick Start

Get up and running in minutes! Here's how easy it is to integrate with Shopee:

```typescript
import { ShopeeSDK, ShopeeRegion } from '@congminh1254/shopee-sdk';

// 1. Initialize the SDK with your credentials
const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-partner-key',
  region: ShopeeRegion.GLOBAL,
  shop_id: 789012, // Optional for shop-specific operations
});

// 2. Authenticate your shop (OAuth flow)
const authUrl = sdk.getAuthorizationUrl('https://your-app.com/callback');
console.log('Visit:', authUrl);

// After user authorizes, exchange code for token (automatic token storage!)
await sdk.authenticateWithCode('auth-code-from-callback');

// 3. Start using the API - it's that simple!

// Manage your products
const products = await sdk.product.getItemList({
  offset: 0,
  page_size: 20,
});

// Process orders
const orders = await sdk.order.getOrderList({
  time_range_field: 'create_time',
  time_from: Math.floor(Date.now() / 1000) - 86400,
  time_to: Math.floor(Date.now() / 1000),
  page_size: 50,
});

// Track shipments
const shipping = await sdk.logistics.getShippingParameter({
  order_sn: '220615ABCDEF',
});

// Handle returns
const returns = await sdk.returns.getReturnList({
  page_size: 20,
});

// And much more - all with full TypeScript support! 🎉
```

**That's it!** The SDK handles token refresh, request signing, error handling, and more automatically.

See the [Setup Guide](./docs/guides/setup.md) and [Authentication Guide](./docs/guides/authentication.md) for detailed instructions.

## Why Choose This SDK?

### 🚀 Production-Ready & Battle-Tested
- **95%+ test coverage** with 671 comprehensive tests - ensuring reliability in production
- **Zero compromises** - Every Shopee API endpoint is implemented and documented
- **Type-safe** - Full TypeScript definitions prevent errors before they happen
- **Actively maintained** - Regular updates to stay in sync with Shopee API changes

### 💪 Complete API Coverage - All 29 Managers Implemented
Unlike other SDKs with partial coverage, we provide **complete access** to every Shopee API:

**Core Commerce:**
- 📦 **ProductManager** - Full product catalog management with 55+ endpoints
- 🛒 **OrderManager** - Complete order processing and fulfillment workflow
- 🚚 **LogisticsManager** - Comprehensive shipping and tracking operations
- 💳 **PaymentManager** - Payment and escrow information management

**Marketing & Promotions:**
- 🎟️ **VoucherManager** - Discount voucher campaigns
- 💥 **DiscountManager** - Discount promotion campaigns
- 🎁 **BundleDealManager** - Bundle deal promotions
- ➕ **AddOnDealManager** - Add-on deal promotions
- ⚡ **ShopFlashSaleManager** - Flash sale campaigns
- 🎯 **FollowPrizeManager** - Follow prize activities
- ⭐ **TopPicksManager** - Top picks product collections
- 📣 **AmsManager** - Affiliate marketing solutions (AMS)

**Store Management:**
- 🏪 **ShopManager** - Shop information and profile management
- 🏢 **MerchantManager** - Merchant information, warehouses, and multi-shop management
- 📂 **ShopCategoryManager** - Shop category organization
- 🖼️ **MediaManager** & **MediaSpaceManager** - Image and video upload operations

**Advanced Features:**
- 🔐 **AuthManager** - OAuth flow and token lifecycle management
- 📢 **PushManager** - Webhooks and real-time notifications
- 🌍 **GlobalProductManager** - Cross-border product management
- 🔄 **ReturnsManager** - Return and refund request handling
- 📊 **AdsManager** - Advertising campaign management
- 📈 **AccountHealthManager** - Performance metrics and analytics
- 🌐 **PublicManager** - Public API endpoints (no auth required)
- 📍 **FirstMileManager** - First mile logistics operations
- 🏭 **SbsManager** - Shopee Business Services warehouse inventory
- 📦 **FbsManager** - Fulfillment by Shopee operations
- 📹 **LivestreamManager** - Live streaming features
- 🎬 **VideoManager** - Shopee Video features and analytics

### ✨ Developer Experience First
- **Intuitive API design** - Clean, consistent interfaces across all managers
- **Automatic token refresh** - Built-in token management, never worry about expiration
- **Flexible storage** - File-based storage included, easy to implement custom solutions
- **Multi-region support** - Works seamlessly across all 12 Shopee regions
- **Proxy support** - Enterprise-ready HTTP/HTTPS proxy configuration
- **Comprehensive docs** - Detailed guides and real-world examples for every feature
- **Full type safety** - Complete TypeScript definitions for autocomplete and error prevention

## Real-World Use Cases

This SDK is perfect for building:

- 🏪 **Multi-channel E-commerce Platforms** - Sync inventory, orders, and products across multiple sales channels
- 📊 **Analytics Dashboards** - Track sales performance, customer behavior, and business metrics
- 🤖 **Automation Tools** - Automate order processing, inventory updates, and customer communications
- 🔄 **ERP Integrations** - Connect Shopee with your existing business systems
- 📱 **Mobile Apps** - Build native mobile experiences for shop management
- 🎯 **Marketing Automation** - Manage promotions, vouchers, and advertising campaigns programmatically
- 📦 **Inventory Management Systems** - Real-time stock tracking across warehouses
- 🚀 **Custom Storefronts** - Create unique shopping experiences powered by Shopee's infrastructure

## Migrating from Other SDKs?

Switching is easy! Our SDK offers:
- **More complete coverage** - Every endpoint is implemented, not just the basics
- **Better TypeScript support** - Full type safety from end to end
- **Simpler API** - Intuitive, well-organized manager classes
- **Active maintenance** - Regular updates and community support
- **Production-ready** - Battle-tested with comprehensive test coverage

Check our [Migration Guide](./docs/guides/setup.md) to get started.

## Contributing

We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages to automate versioning and release notes.

Examples of commit messages:

- `feat: add support for logistics API` - Minor version bump
- `fix: correct error handling in order API` - Patch version bump
- `docs: update API documentation` - No version bump
- `feat!: rename parameters in product API` or `feat: rename parameters in product API BREAKING CHANGE: ...` - Major version bump

## Release Process

This project uses [Release Please](https://github.com/googleapis/release-please) to automate version management and releases.

The release process follows these steps:

1. Commits to the main branch are automatically analyzed
2. When conventional commit messages are detected, Release Please creates or updates a release PR
3. When the release PR is merged:
   - A new GitHub tag and release is created
   - The package is automatically published to npm
   - The CHANGELOG.md is updated with the release notes

## License

MIT