@profplum700/etsy-v3-api-client/CHANGELOG.md

JavaScript/TypeScript client for the Etsy Open API v3 with OAuth 2.0 authentication

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Fixed
- **@profplum700/etsy-nextjs**: Fixed "createContext is not a function" build error in Next.js API routes
  - **BREAKING**: Main entry point (`@profplum700/etsy-nextjs`) now exports only server-side code
  - Client-side exports (`EtsyNextClientProvider`, `useEtsyNextClient`) must be imported from `@profplum700/etsy-nextjs/client`
  - This prevents React Context code from being bundled with API routes during Next.js build
  - Server imports from both `@profplum700/etsy-nextjs` and `@profplum700/etsy-nextjs/server` work identically
  - See MIGRATION.md for upgrade instructions

## [2.5.4] - 2026-03-31

### Fixed
- Restored the original flexible payload typing in `EtsyWebhookHandler.parseEvent()` so webhook parsing continues to accept existing object payloads without over-constraining the input.
- Corrected the default Etsy API rate-limiting assumptions to Etsy's actual documented limits: `5` requests per second and `5,000` requests per day.

### Changed
- Prepared a synchronized patch release across the root package and workspace packages so the published versions stay aligned again.

## [2.3.1] - 2025-11-07

### Fixed
- **@profplum700/etsy-react**: replaced `@testing-library/react-hooks` with `@testing-library/react` in tests to remove stale React 16/17 peer dependency warnings.
- **@profplum700/etsy-react**: introduced a dedicated build tsconfig and Rollup configuration tweaks to eliminate TypeScript plugin warnings during bundling.

### Changed
- Bumped the root workspace plus `@profplum700/etsy-react`, `@profplum700/etsy-admin-ui`, `@profplum700/etsy-nextjs`, and `@profplum700/etsy-cli` to version `2.3.1` to publish the fix consistently across the monorepo.

## [2.3.0] - 2025-01-06

### 🎉 PHASE 3: Ecosystem Integration

This release implements **Phase 3 of the Roadmap**, transforming the project into a comprehensive **monorepo** with multiple integration packages for different platforms and use cases.

#### 🏗️ **Monorepo Structure**
- Converted project to pnpm workspace monorepo
- Created `packages/` directory for integration packages
- Added workspace-aware build, test, and lint scripts
- All packages published independently under `@profplum700` scope

#### 📦 **New Packages**

##### **@profplum700/etsy-react** - React Hooks Library
- Complete set of React hooks for Etsy API
- Query hooks: `useShop`, `useListings`, `useReceipts`, `useListing`, `useReceipt`, `useShopSections`
- Mutation hooks: `useUpdateListing`, `useCreateDraftListing`, `useDeleteListing`, `useUpdateInventory`, `useUploadListingImage`, `useDeleteListingImage`, `useUpdateReceipt`, `useCreateShippingProfile`
- Core hooks: `useQuery`, `useMutation` with auto-refetch, error handling, and loading states
- `EtsyProvider` context for client management
- Full TypeScript support with comprehensive type definitions
- Automatic pagination with `loadMore` and `hasMore` support
- Configurable refetch on interval and window focus

##### **@profplum700/etsy-nextjs** - Next.js Integration
- Full Next.js 14+ support with App Router
- Server-side utilities: `getEtsyServerClient`, `createEtsyServerClient`, `configureEtsyServerClient`
- API route helpers with `createEtsyApiRoute`
- Built-in rate limiting and caching for API routes
- Cookie-based token storage for server components
- Client-side `EtsyNextClientProvider` for client components
- Edge Runtime compatibility
- Server Components support for SSR and SSG
- TypeScript definitions for all functions

##### **@profplum700/etsy-cli** - Command-Line Tool
- Global CLI installation: `npm install -g @profplum700/etsy-cli`
- Authentication management: `etsy auth configure`, `etsy auth status`
- Shop operations: `etsy shops get`, `etsy shops sections`
- Listing management: `etsy listings list`, `etsy listings get`, `etsy listings delete`
- Order fulfillment: `etsy receipts list`, `etsy receipts get`
- Image operations: `etsy images upload`, `etsy images delete`
- Rich terminal UI with tables, spinners, and colored output
- JSON export option for all commands
- Filter and pagination support
- Configuration stored in `~/.etsy-cli/`

##### **@profplum700/etsy-admin-ui** - Admin Dashboard Components
- Pre-built React components for admin dashboards
- `ShopDashboard` - Shop overview with stats and details
- `ListingManager` - Grid view with filtering, activate/deactivate, delete actions
- `OrderFulfillment` - Order list with fulfillment tracking
- `InventoryTracker` - Inventory monitoring with low stock alerts
- `Layout`, `Header`, `Sidebar`, `SidebarItem` - Layout components
- Responsive design with mobile support
- Default CSS stylesheet included
- Dark mode ready with CSS variables
- Fully customizable styling
- TypeScript support with comprehensive prop types

#### 📚 **Documentation**
- Created comprehensive `PACKAGES.md` documenting all packages
- Individual README files for each package with examples
- Quick start guides for each integration
- API reference documentation
- Usage examples for common scenarios
- Monorepo development guide

#### 🔧 **Infrastructure**
- Added pnpm workspace configuration
- Updated root package.json with monorepo scripts
- Build pipeline supports all packages
- Unified testing across packages
- Shared ESLint and TypeScript configurations
- Version bumped to 2.3.0 across all packages

### Fixed
- **CRITICAL**: Fixed 204 No Content response handling in DELETE operations
  - DELETE endpoints (`deleteShopSection`, `deleteListing`, `deleteListingImage`, `deleteShopShippingProfile`, `deleteShopShippingProfileDestination`) now properly handle 204 responses without throwing errors
  - Added defensive checks for empty response bodies and content-length headers
  - All DELETE operations now return `undefined` for successful 204 responses
  - Added comprehensive tests for 204 response handling
  - **Impact**: Previously, successful DELETE operations would fail with "SyntaxError: Unexpected end of JSON input"

- Fixed GitHub Actions CI workflow to use pnpm instead of npm
  - Added `pnpm/action-setup@v4` to install pnpm
  - Changed cache from "npm" to "pnpm"
  - Updated all commands to use pnpm
  - Resolves lock file mismatch errors in CI pipeline

### Changed
- **Code Quality**: Fixed all 205 ESLint errors and warnings
  - Removed unused imports and variables across test files
  - Updated ESLint config to allow `any` types and implicit return types in test files
  - Added `globals@16.5.0` as dev dependency
  - Zero linting issues remaining

## [2.0.0] - 2025-01-06

### 🎉 MAJOR RELEASE: Complete Etsy v3 API Support

This release transforms the client into a **comprehensive, production-ready Etsy v3 SDK** with support for **60+ additional endpoints** covering ALL major Etsy API operations.

### 🔒 Security Improvements

#### **File Permission Security**
- `FileTokenStorage` now automatically sets restrictive file permissions (0o600 - owner read/write only)
- Prevents unauthorized access to token files on Unix-like systems
- Gracefully handles platforms that don't support chmod (e.g., Windows)

#### **Error Message Sanitization**
- Removed sensitive data from error messages during token refresh
- Error responses no longer include potentially sensitive API error details
- Reduces risk of accidental credential exposure in logs

#### **Security Documentation**
- Added comprehensive `SECURITY.md` with:
  - Security features overview
  - Best practices for production deployments
  - Known security considerations and mitigations
  - Vulnerability reporting process
  - Production security checklist

#### **Token Storage Warnings**
- Added security warnings to `FileTokenStorage` class documentation
- Clarifies that tokens are stored in plaintext
- Recommends encrypted storage for production use
- Emphasizes .gitignore for token files

### Added

#### **Shop Management Endpoints**
- `updateShop()` - Update shop settings (title, announcement, messages)
- `createShopSection()` - Create new shop sections
- `updateShopSection()` - Update existing shop sections
- `deleteShopSection()` - Delete shop sections

#### **Listing Write Operations**
- `createDraftListing()` - Create new draft listings with full customization
- `updateListing()` - Update existing listings (title, description, pricing, etc.)
- `deleteListing()` - Delete listings
- `updateListingInventory()` - Update inventory, variations, and offerings

#### **Listing Image Management**
- `uploadListingImage()` - Upload images to listings with metadata
- `getListingImage()` - Get specific listing image details
- `deleteListingImage()` - Delete listing images

#### **Shop Receipts/Orders (Complete Order Management)**
- `getShopReceipts()` - Get all shop receipts with advanced filtering
- `getShopReceipt()` - Get specific receipt details
- `updateShopReceipt()` - Update receipt status and seller messages
- `getShopReceiptTransactions()` - Get all transactions for a receipt
- `getShopTransaction()` - Get specific transaction details

#### **Shipping Profiles (Full Shipping Management)**
- `getShopShippingProfiles()` - List all shipping profiles
- `createShopShippingProfile()` - Create new shipping profiles
- `getShopShippingProfile()` - Get specific profile details
- `updateShopShippingProfile()` - Update shipping profiles
- `deleteShopShippingProfile()` - Delete shipping profiles
- `getShopShippingProfileDestinations()` - Get profile destinations
- `createShopShippingProfileDestination()` - Add shipping destinations
- `updateShopShippingProfileDestination()` - Update destinations
- `deleteShopShippingProfileDestination()` - Delete destinations
- `getShopShippingProfileUpgrades()` - Get shipping upgrades

#### **Fulfillment & Shipment Tracking**
- `createReceiptShipment()` - Add tracking information to orders

#### **Payment & Financial Data**
- `getShopPaymentAccountLedgerEntries()` - Get payment ledger entries
- `getShopPaymentAccountLedgerEntry()` - Get specific ledger entry
- `getShopPayment()` - Get payment details

#### **Extended Taxonomy & Properties**
- `getBuyerTaxonomyNodes()` - Get buyer-facing taxonomy
- `getPropertiesByTaxonomyId()` - Get properties for a category
- `getListingProperties()` - Get properties for a listing

#### **Shop Production Partners**
- `getShopProductionPartners()` - Get production partner information

### New Types & Interfaces

Added **40+ new TypeScript interfaces** for comprehensive type safety:

- **Shop Management**: `UpdateShopParams`, `CreateShopSectionParams`, `UpdateShopSectionParams`
- **Receipts/Orders**: `EtsyShopReceipt`, `EtsyShopReceiptTransaction`, `EtsyShopReceiptShipment`, `EtsyShopRefund`, `EtsyTransactionVariation`, `GetShopReceiptsParams`, `UpdateShopReceiptParams`
- **Shipping**: `EtsyShippingProfile`, `EtsyShippingProfileDestination`, `EtsyShippingProfileUpgrade`, `CreateShippingProfileParams`, `UpdateShippingProfileParams`, etc.
- **Payments**: `EtsyPaymentAccountLedgerEntry`, `EtsyPaymentAdjustment`, `EtsyPayment`, `GetPaymentAccountLedgerEntriesParams`
- **Listings**: `CreateDraftListingParams`, `UpdateListingParams`, `UpdateListingInventoryParams`
- **Properties**: `EtsyListingProperty`, `EtsyListingPropertyScale`
- **Taxonomy**: `EtsyBuyerTaxonomyNode`, `EtsyBuyerTaxonomyProperty`, `EtsyBuyerTaxonomyPropertyScale`, `EtsyBuyerTaxonomyPropertyValue`
- **Production**: `EtsyShopProductionPartner`
- **File Uploads**: `UploadListingImageParams`, `UploadListingFileParams`

### API Coverage Summary

**Total Endpoint Count**: **70+ endpoints** (up from 13)

- ✅ **User Management**: 2 endpoints
- ✅ **Shop Management**: 7 endpoints (4 new)
- ✅ **Shop Sections**: 4 endpoints (2 new)
- ✅ **Listings (Read)**: 5 endpoints
- ✅ **Listings (Write)**: 4 endpoints (NEW)
- ✅ **Listing Images**: 4 endpoints (3 new)
- ✅ **Listing Inventory**: 2 endpoints (1 new)
- ✅ **Listing Properties**: 1 endpoint (NEW)
- ✅ **Shop Receipts/Orders**: 5 endpoints (NEW)
- ✅ **Transactions**: 2 endpoints (NEW)
- ✅ **Shipping Profiles**: 10 endpoints (NEW)
- ✅ **Shipments**: 2 endpoints (NEW)
- ✅ **Payments & Ledger**: 3 endpoints (NEW)
- ✅ **Taxonomy**: 3 endpoints (2 new)
- ✅ **Production Partners**: 1 endpoint (NEW)

### Enhanced Features

- **Full CRUD Operations**: Complete Create, Read, Update, Delete support for listings, sections, shipping profiles
- **Order Management**: Complete order/receipt lifecycle management
- **Fulfillment Workflow**: Full shipping and tracking integration
- **Financial Tracking**: Access to payment ledgers and financial data
- **Advanced Filtering**: Sophisticated query parameters for receipts, ledger entries, and more
- **Image Upload**: Multipart form data support for image uploads with metadata
- **Type Safety**: Comprehensive TypeScript types for all new endpoints

### Breaking Changes

None - This release is **backward compatible** with v1.x. All existing endpoints continue to work as before.

### Technical Improvements

- Fixed TypeScript FormData type issue with Buffer support
- Enhanced type exports in index.ts
- Improved JSDoc comments for all new methods
- Consistent error handling across all new endpoints
- Proper cache control for write operations (cache disabled for POST/PUT/PATCH/DELETE)

### Developer Experience

- **Complete API Coverage**: Support for virtually all Etsy v3 seller operations
- **Production Ready**: Suitable for complete shop management applications
- **Full Type Safety**: IntelliSense support for all new types and endpoints
- **Consistent Patterns**: All new endpoints follow established API patterns
- **Comprehensive Documentation**: Inline JSDoc with endpoint URLs and required scopes

### Migration Guide

No migration required! Simply update to v2.0.0 to access the new endpoints. All existing code continues to work without changes.

```typescript
// New capabilities available immediately
const client = new EtsyClient(config);

// Create a new listing
const listing = await client.createDraftListing(shopId, {
  title: "Handmade Widget",
  description: "Beautiful handcrafted widget",
  price: 29.99,
  quantity: 10,
  // ... more params
});

// Upload images
await client.uploadListingImage(shopId, listing.listing_id.toString(), imageBlob);

// Manage orders
const receipts = await client.getShopReceipts(shopId, { was_paid: true });

// Add tracking
await client.createReceiptShipment(shopId, receiptId, {
  tracking_code: "1Z999AA10123456784",
  carrier_name: "UPS"
});
```

## [1.0.0-beta.2] - 2024-01-13

### Fixed
- **Test Suite**: Fixed all remaining test failures (167/167 tests now passing)
- **Rate Limiting**: Fixed rate limiter configuration in EtsyClient constructor to properly respect `minRequestInterval`
- **Token Manager**: Fixed fs mocking issues in FileTokenStorage tests
- **Integration Tests**: Fixed timing issues and caching interference in rate limiting tests
- **Daily Reset**: Improved rate limiter daily reset logic and testing
- **Caching**: Fixed caching interference with rate limiting tests by allowing cache disable

### Added
- **Testing Guide**: Added comprehensive `TEST_PACKAGE.md` with step-by-step testing instructions
- **Type Support**: Added `minRequestInterval` to EtsyClientConfig interface

### Changed
- **Rate Limiter**: Enhanced rate limiter to properly handle edge cases and large daily limits
- **Error Handling**: Improved error propagation in client makeRequest method

### Technical Improvements
- 100% test coverage with all 167 tests passing
- Improved timer handling in tests using fake timers
- Better mock isolation in integration tests
- Enhanced rate limiter state management

## [1.0.0-beta.1] - 2024-01-13

### Added
- Initial beta release of the Etsy API v3 client
- OAuth 2.0 authentication with PKCE flow support
- Complete TypeScript definitions for all API responses
- Rate limiting with respect to Etsy's API limits (5,000/day, 5/second)
- Automatic token refresh with configurable storage
- Response caching for GET requests
- Support for all major Etsy API v3 endpoints:
  - User management (`getUser`)
  - Shop management (`getShop`, `getShopByOwnerUserId`) 
  - Listing operations (`getListing`, `getListingsByShop`, `findAllListingsActive`)
- Multiple token storage options:
  - `MemoryTokenStorage` for temporary storage
  - `FileTokenStorage` for persistent file-based storage
  - Custom storage interface support
- Comprehensive error handling with specific error types:
  - `EtsyApiError` for API-related errors
  - `EtsyAuthError` for authentication errors
  - `EtsyRateLimitError` for rate limiting violations
- Universal compatibility (Node.js 18+ and modern browsers)
- Built-in fetch fallback for older Node.js versions
- Configurable base URLs for testing and custom endpoints
- Extensive test coverage with Jest
- Full ES modules support with CommonJS compatibility

### Features
- **AuthHelper**: Complete OAuth 2.0 flow implementation with PKCE
- **EtsyClient**: Main API client with automatic token management
- **TokenManager**: Handles token refresh and storage persistence
- **EtsyRateLimiter**: Built-in rate limiting to prevent API violations
- **Caching**: Optional response caching with TTL support
- **TypeScript**: Full type safety with comprehensive interface definitions

### Configuration Options
- Rate limiting can be customized or disabled
- Caching can be enabled/disabled with custom TTL
- Token refresh callbacks for custom storage handling
- Custom logger interface support
- Flexible scope management with predefined combinations

### Scope Support
- Read scopes: `shops_r`, `listings_r`, `profile_r`, `favorites_r`, etc.
- Write scopes: `shops_w`, `listings_w`, `profile_w`, etc.
- Delete scopes: `shops_d`, `listings_d`, etc.
- Transaction and billing scopes: `transactions_r`, `billing_r`
- Predefined scope combinations for common use cases

### API Coverage
- User operations: Get current user information
- Shop operations: Get shop details, search shops by user
- Listing operations: Get individual listings, shop listings, search active listings
- Support for pagination, filtering, and sorting
- Include parameters for related data fetching

### Developer Experience
- Comprehensive documentation and examples
- IDE-friendly with full IntelliSense support
- Clear error messages with actionable information
- Consistent API design patterns
- Zero-configuration setup with sensible defaults

### Technical Details
- Built with Rollup for optimal bundling
- ES modules with CommonJS compatibility
- Tree-shakeable exports
- No runtime dependencies except node-fetch (for older Node.js)
- Supports both named and default imports
- Works in server-side and client-side environments

## [Unreleased]

### Planned
- Additional API endpoint coverage
- Webhook support
- Advanced pagination helpers
- Request retry logic with exponential backoff
- Enhanced caching strategies
- More storage adapter options
- Performance optimizations
- Additional examples and tutorials

---

## Notes

This changelog follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.

For upgrade instructions and breaking changes, see the [Migration Guide](./MIGRATION.md) (when available).

## Version Schema

- `MAJOR.MINOR.PATCH` for stable releases
- `MAJOR.MINOR.PATCH-beta.N` for beta releases
- `MAJOR.MINOR.PATCH-alpha.N` for alpha releases

## Support

- For bug reports and feature requests, please use [GitHub Issues](https://github.com/profplum700/etsy-v3-api-client/issues)
- For questions and discussions, see [GitHub Discussions](https://github.com/profplum700/etsy-v3-api-client/discussions)