@congminh1254/shopee-sdk
Version:
Shopee SDK maintaining by community
272 lines (202 loc) • 12.8 kB
Markdown
# Shopee SDK
[](https://github.com/congminh1254/shopee-sdk/actions/workflows/ci.yml)
[](https://coveralls.io/github/congminh1254/shopee-sdk?branch=main)
[](https://badge.fury.io/js/@congminh1254%2Fshopee-sdk)
[](https://www.npmjs.com/package/@congminh1254/shopee-sdk)
[](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
- **100% core test coverage** with 700+ robust unit & live sandbox integration tests - ensuring ultimate production reliability
- **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.
## 🧪 Testing & Quality Assurance
This SDK is built with reliability and correctness as first-class citizens, boasting extensive test coverage across both simulated unit environments and live external sandbox systems.
### 1. Unit Tests
- **Mock Manager Coverage**: Over **690+ unit tests** validating standard parameters, response layouts, request sign-generation, and error boundaries for all 29 API managers.
- **100% Code Coverage**: All core and manager logic files maintain a strict **100% statement, branch, and line code coverage**.
- Run unit tests:
```bash
npm run test
```
### 2. Live Sandbox Integration Tests
Our integration test suite executes real HTTP requests against the **live Shopee Sandbox environment** (using dynamic OAuth credentials) to verify end-to-end integration safety:
- **Vouchers**: Tests the full CRUD lifecycle (creating, fetching, updating limits, and automatically cleaning up/deleting test vouchers).
- **Media & Videos**: Verifies safe transparent PNG uploads, video session initialization, and a complete chunked video upload workflow utilizing a built-in, highly-optimized 10-second Base64 MP4 H.264 video fixture.
- **Logistics & Documents**: Validates thermal shipping label document generation and download jobs.
- **Payments & Settings**: Checks public payment methods, shop installment profiles, active orders, local products, and dynamic Shopee server IP ranges.
- Run sandbox integration tests:
```bash
npm run test:sandbox
```
## 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