@profplum700/etsy-v3-api-client 2.5.3 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/CHANGELOG.md +21 -12
  2. package/README.md +138 -130
  3. package/dist/.tsbuildinfo +1 -1
  4. package/dist/browser.esm.js +64 -23
  5. package/dist/browser.esm.js.map +1 -1
  6. package/dist/browser.umd.js +1 -1
  7. package/dist/browser.umd.js.map +1 -1
  8. package/dist/index.cjs +67 -24
  9. package/dist/index.cjs.map +1 -1
  10. package/dist/index.d.ts +39 -5
  11. package/dist/index.esm.js +67 -25
  12. package/dist/index.esm.js.map +1 -1
  13. package/dist/node.cjs +67 -24
  14. package/dist/node.cjs.map +1 -1
  15. package/dist/node.esm.js +67 -25
  16. package/dist/node.esm.js.map +1 -1
  17. package/package.json +1 -1
  18. package/dist/index.js +0 -8517
  19. package/dist/index.js.map +0 -1
  20. package/dist/index.umd.js +0 -1180
  21. package/dist/index.umd.js.map +0 -1
  22. package/dist/index.umd.min.js +0 -2
  23. package/dist/index.umd.min.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -5,17 +5,26 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
- ## [Unreleased]
9
-
10
- ### Fixed
11
- - **@profplum700/etsy-nextjs**: Fixed "createContext is not a function" build error in Next.js API routes
12
- - **BREAKING**: Main entry point (`@profplum700/etsy-nextjs`) now exports only server-side code
13
- - Client-side exports (`EtsyNextClientProvider`, `useEtsyNextClient`) must be imported from `@profplum700/etsy-nextjs/client`
14
- - This prevents React Context code from being bundled with API routes during Next.js build
15
- - Server imports from both `@profplum700/etsy-nextjs` and `@profplum700/etsy-nextjs/server` work identically
16
- - See MIGRATION.md for upgrade instructions
17
-
18
- ## [2.3.1] - 2025-11-07
8
+ ## [Unreleased]
9
+
10
+ ### Fixed
11
+ - **@profplum700/etsy-nextjs**: Fixed "createContext is not a function" build error in Next.js API routes
12
+ - **BREAKING**: Main entry point (`@profplum700/etsy-nextjs`) now exports only server-side code
13
+ - Client-side exports (`EtsyNextClientProvider`, `useEtsyNextClient`) must be imported from `@profplum700/etsy-nextjs/client`
14
+ - This prevents React Context code from being bundled with API routes during Next.js build
15
+ - Server imports from both `@profplum700/etsy-nextjs` and `@profplum700/etsy-nextjs/server` work identically
16
+ - See MIGRATION.md for upgrade instructions
17
+
18
+ ## [2.5.4] - 2026-03-31
19
+
20
+ ### Fixed
21
+ - Restored the original flexible payload typing in `EtsyWebhookHandler.parseEvent()` so webhook parsing continues to accept existing object payloads without over-constraining the input.
22
+ - Corrected the default Etsy API rate-limiting assumptions to Etsy's actual documented limits: `5` requests per second and `5,000` requests per day.
23
+
24
+ ### Changed
25
+ - Prepared a synchronized patch release across the root package and workspace packages so the published versions stay aligned again.
26
+
27
+ ## [2.3.1] - 2025-11-07
19
28
 
20
29
  ### Fixed
21
30
  - **@profplum700/etsy-react**: replaced `@testing-library/react-hooks` with `@testing-library/react` in tests to remove stale React 16/17 peer dependency warnings.
@@ -331,7 +340,7 @@ await client.createReceiptShipment(shopId, receiptId, {
331
340
  - Initial beta release of the Etsy API v3 client
332
341
  - OAuth 2.0 authentication with PKCE flow support
333
342
  - Complete TypeScript definitions for all API responses
334
- - Rate limiting with respect to Etsy's API limits (10,000/day, 10/second)
343
+ - Rate limiting with respect to Etsy's API limits (5,000/day, 5/second)
335
344
  - Automatic token refresh with configurable storage
336
345
  - Response caching for GET requests
337
346
  - Support for all major Etsy API v3 endpoints:
package/README.md CHANGED
@@ -4,9 +4,9 @@
4
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
5
  [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
6
6
 
7
- A modern, universal TypeScript/JavaScript client for the Etsy Open API v3 with full OAuth 2.0 PKCE authentication support. Works seamlessly in both browser and Node.js environments.
8
-
9
- This repository is heavily based on the official Etsy OpenAPI specification (`https://www.etsy.com/openapi/generated/oas/3.0.0.json`), as referenced in Etsy's API documentation (`https://developers.etsy.com/documentation/reference`).
7
+ A modern, universal TypeScript/JavaScript client for the Etsy Open API v3 with full OAuth 2.0 PKCE authentication support. Works seamlessly in both browser and Node.js environments.
8
+
9
+ This repository is heavily based on the official Etsy OpenAPI specification (`https://www.etsy.com/openapi/generated/oas/3.0.0.json`), as referenced in Etsy's API documentation (`https://developers.etsy.com/documentation/reference`).
10
10
 
11
11
  ## 🚀 Features
12
12
 
@@ -59,7 +59,7 @@ const tokens = await authHelper.getAccessToken();
59
59
  // Create API client
60
60
  const client = new EtsyClient({
61
61
  keystring: 'your-api-key',
62
- sharedSecret: 'your-shared-secret', // Required for new API key format
62
+ sharedSecret: 'your-shared-secret', // REQUIRED for v3 API compliance
63
63
  accessToken: tokens.access_token,
64
64
  refreshToken: tokens.refresh_token,
65
65
  expiresAt: tokens.expires_at
@@ -172,7 +172,7 @@ const client = new EtsyClient({
172
172
  // Optional configuration
173
173
  rateLimiting: {
174
174
  enabled: true,
175
- maxRequestsPerSecond: 10,
175
+ maxRequestsPerSecond: 5,
176
176
  maxRequestsPerDay: 5000
177
177
  },
178
178
  caching: {
@@ -198,11 +198,11 @@ const listings = await client.getListingsByShop('shop-id');
198
198
  const listing = await client.getListing('listing-id');
199
199
 
200
200
  // Search listings
201
- const searchResults = await client.findAllListingsActive({
202
- keywords: 'vintage',
203
- taxonomy_id: 123,
204
- limit: 25
205
- });
201
+ const searchResults = await client.findAllListingsActive({
202
+ keywords: 'vintage',
203
+ taxonomy_id: 123,
204
+ limit: 25
205
+ });
206
206
  ```
207
207
 
208
208
  ### Error Handling
@@ -292,9 +292,9 @@ const client = new EtsyClient({
292
292
  // ... other config
293
293
  rateLimiting: {
294
294
  enabled: true,
295
- maxRequestsPerSecond: 10, // Requests per second
296
- maxRequestsPerDay: 5000, // Requests per day
297
- minRequestInterval: 100 // Minimum ms between requests
295
+ maxRequestsPerSecond: 5, // Requests per second (Etsy's limit)
296
+ maxRequestsPerDay: 5000, // Requests per day (Etsy's limit)
297
+ minRequestInterval: 200 // Minimum ms between requests (1000 / 5 QPS)
298
298
  }
299
299
  });
300
300
 
@@ -356,121 +356,129 @@ The package provides optimized builds for different environments:
356
356
  - `getShop(shopId)` - Get shop details
357
357
  - `getShopByOwnerUserId(userId)` - Get shop by owner user ID
358
358
 
359
- #### Listing Methods
360
- - `getListing(listingId)` - Get listing details
361
- - `getListingsByShop(shopId, options?)` - Get shop's listings
362
- - `findAllListingsActive(options?)` - Search active listings
363
-
364
- #### Listing Management Endpoint Support
365
- | Category | Endpoint | Supported |
366
- | --- | --- | --- |
367
- | BuyerTaxonomy | getBuyerTaxonomyNodes | Yes |
368
- | BuyerTaxonomy | getPropertiesByBuyerTaxonomyId | No |
369
- | SellerTaxonomy | getSellerTaxonomyNodes | Yes |
370
- | SellerTaxonomy | getPropertiesByTaxonomyId | Yes |
371
- | ShopListing | createDraftListing | Yes |
372
- | ShopListing | getListingsByShop | Yes |
373
- | ShopListing | deleteListing | Yes |
374
- | ShopListing | getListing | Yes |
375
- | ShopListing | findAllListingsActive | Yes |
376
- | ShopListing | findAllActiveListingsByShop | No |
377
- | ShopListing | getListingsByListingIds | No |
378
- | ShopListing | getFeaturedListingsByShop | No |
379
- | ShopListing | deleteListingProperty | No |
380
- | ShopListing | updateListingProperty | Yes |
381
- | ShopListing | getListingProperty | No |
382
- | ShopListing | getListingProperties | Yes |
383
- | ShopListing | updateListing | Yes |
384
- | ShopListing | getListingsByShopReceipt | No |
385
- | ShopListing | getListingsByShopReturnPolicy | No |
386
- | ShopListing | getListingsByShopSectionId | No |
387
- | ShopListing File | deleteListingFile | No |
388
- | ShopListing File | getListingFile | No |
389
- | ShopListing File | getAllListingFiles | No |
390
- | ShopListing File | uploadListingFile | No |
391
- | ShopListing Image | deleteListingImage | Yes |
392
- | ShopListing Image | getListingImage | Yes |
393
- | ShopListing Image | getListingImages | Yes |
394
- | ShopListing Image | uploadListingImage | Yes |
395
- | ShopListing Inventory | getListingInventory | Yes |
396
- | ShopListing Inventory | updateListingInventory | Yes |
397
- | ShopListing Offering | getListingOffering | No |
398
- | ShopListing Product | getListingProduct | No |
399
- | ShopListing Translation | createListingTranslation | No |
400
- | ShopListing Translation | getListingTranslation | No |
401
- | ShopListing Translation | updateListingTranslation | No |
402
- | ShopListing VariationImage | getListingVariationImages | No |
403
- | ShopListing VariationImage | updateVariationImages | No |
404
- | ShopListing Video | deleteListingVideo | No |
405
- | ShopListing Video | getListingVideo | No |
406
- | ShopListing Video | getListingVideos | No |
407
- | ShopListing Video | uploadListingVideo | No |
408
- | Other | ping | No |
409
- | Other | tokenScopes | No |
410
- | Ledger Entry | getShopPaymentAccountLedgerEntry | Yes |
411
- | Ledger Entry | getShopPaymentAccountLedgerEntries | Yes |
412
- | Payment | getShopPaymentByReceiptId | No |
413
- | Payment | getPaymentAccountLedgerEntry | No |
414
- | Payment | getPayments | No |
415
- | Shop Receipt | getShopReceipt | Yes |
416
- | Shop Receipt | updateShopReceipt | Yes |
417
- | Shop Receipt | getShopReceipts | Yes |
418
- | Shop Receipt | searchAllShopReceipts | No |
419
- | Shop Receipt Transactions | getShopReceiptTransaction | Yes |
420
- | Shop Receipt Transactions | getShopReceiptTransactionsByListing | No |
421
- | Shop Receipt Transactions | getShopReceiptTransactionsByReceipt | Yes |
422
- | Shop Receipt Transactions | getShopReceiptTransactionsByShop | No |
423
- | Review | getReviewsByListing | Yes |
424
- | Review | getReviewsByShop | Yes |
425
- | Shop HolidayPreferences | getShopHolidayPreferences | No |
426
- | Shop HolidayPreferences | updateShopHolidayPreferences | No |
427
- | Shop ProcessingProfiles | createShopShippingProfileUpgrade | No |
428
- | Shop ProcessingProfiles | getShopShippingProfileUpgrades | Yes |
429
- | Shop ProcessingProfiles | deleteShopShippingProfileUpgrade | No |
430
- | Shop ProcessingProfiles | getShopShippingProfileUpgrade | No |
431
- | Shop ProcessingProfiles | updateShopShippingProfileUpgrade | No |
432
- | Shop ShippingProfile | getShippingCarriers | No |
433
- | Shop ShippingProfile | createShopShippingProfile | Yes |
434
- | Shop ShippingProfile | getShopShippingProfiles | Yes |
435
- | Shop ShippingProfile | deleteShopShippingProfile | Yes |
436
- | Shop ShippingProfile | getShopShippingProfile | Yes |
437
- | Shop ShippingProfile | updateShopShippingProfile | Yes |
438
- | Shop ShippingProfile | createShopShippingProfileDestination | Yes |
439
- | Shop ShippingProfile | getShopShippingProfileDestinationsByShippingProfile | Yes |
440
- | Shop ShippingProfile | deleteShopShippingProfileDestination | Yes |
441
- | Shop ShippingProfile | updateShopShippingProfileDestination | Yes |
442
- | Shop ShippingProfile | createShopShippingProfileUpgrade | No |
443
- | Shop ShippingProfile | getShopShippingProfileUpgrades | Yes |
444
- | Shop ShippingProfile | deleteShopShippingProfileUpgrade | No |
445
- | Shop ShippingProfile | updateShopShippingProfileUpgrade | No |
446
- | Shop | getShop | Yes |
447
- | Shop | updateShop | Yes |
448
- | Shop | getShopByOwnerUserId | Yes |
449
- | Shop | findShops | No |
450
- | Shop ProductionPartner | getShopProductionPartners | Yes |
451
- | Shop Section | createShopSection | Yes |
452
- | Shop Section | getShopSections | Yes |
453
- | Shop Section | deleteShopSection | Yes |
454
- | Shop Section | getShopSection | Yes |
455
- | Shop Section | updateShopSection | Yes |
456
- | Shop Return Policy | consolidateShopReturnPolicies | No |
457
- | Shop Return Policy | createShopReturnPolicy | No |
458
- | Shop Return Policy | getShopReturnPolicies | No |
459
- | Shop Return Policy | deleteShopReturnPolicy | No |
460
- | Shop Return Policy | getShopReturnPolicy | No |
461
- | Shop Return Policy | updateShopReturnPolicy | No |
462
- | User | getUser | Yes |
463
- | User | getMe | No |
464
- | UserAddress | deleteUserAddress | No |
465
- | UserAddress | getUserAddress | No |
466
- | UserAddress | getUserAddresses | No |
467
-
468
- #### Review Methods
469
- - `getReviewsByListing(listingId, options?)` - Get reviews for a listing
470
- - `getReviewsByShop(shopId, options?)` - Get reviews for a shop
471
-
472
- #### Search Methods
473
- - `findAllListingsActive(params)` - Search listings with filters
359
+ #### Personalization Methods (New)
360
+ - `getListingPersonalizations(listingId)` - Get personalization questions for a listing
361
+ - `updateListingPersonalization(shopId, listingId, params)` - Create or update personalization questions
362
+ - `deleteListingPersonalization(shopId, listingId)` - Delete personalization
363
+
364
+ #### Listing Methods
365
+ - `getListing(listingId)` - Get listing details
366
+ - `getListingsByShop(shopId, options?)` - Get shop's listings
367
+ - `findAllListingsActive(options?)` - Search active listings
368
+
369
+ #### Listing Management Endpoint Support
370
+ | Category | Endpoint | Supported |
371
+ | --- | --- | --- |
372
+ | BuyerTaxonomy | getBuyerTaxonomyNodes | Yes |
373
+ | BuyerTaxonomy | getPropertiesByBuyerTaxonomyId | No |
374
+ | SellerTaxonomy | getSellerTaxonomyNodes | Yes |
375
+ | SellerTaxonomy | getPropertiesByTaxonomyId | Yes |
376
+ | ShopListing | createDraftListing | Yes |
377
+ | ShopListing | getListingsByShop | Yes |
378
+ | ShopListing | deleteListing | Yes |
379
+ | ShopListing | getListing | Yes |
380
+ | ShopListing | findAllListingsActive | Yes |
381
+ | ShopListing | findAllActiveListingsByShop | No |
382
+ | ShopListing | getListingsByListingIds | No |
383
+ | ShopListing | getFeaturedListingsByShop | No |
384
+ | ShopListing | deleteListingProperty | No |
385
+ | ShopListing | updateListingProperty | Yes |
386
+ | ShopListing | getListingProperty | No |
387
+ | ShopListing | getListingProperties | Yes |
388
+ | ShopListing | updateListing | Yes |
389
+ | ShopListing | getListingsByShopReceipt | No |
390
+ | ShopListing | getListingsByShopReturnPolicy | No |
391
+ | ShopListing | getListingsByShopSectionId | No |
392
+ | ShopListing | getListingPersonalization | Yes |
393
+ | ShopListing | updateListingPersonalization | Yes |
394
+ | ShopListing | deleteListingPersonalization | Yes |
395
+ | ShopListing File | deleteListingFile | No |
396
+ | ShopListing File | getListingFile | No |
397
+ | ShopListing File | getAllListingFiles | No |
398
+ | ShopListing File | uploadListingFile | No |
399
+ | ShopListing Image | deleteListingImage | Yes |
400
+ | ShopListing Image | getListingImage | Yes |
401
+ | ShopListing Image | getListingImages | Yes |
402
+ | ShopListing Image | uploadListingImage | Yes |
403
+ | ShopListing Inventory | getListingInventory | Yes |
404
+ | ShopListing Inventory | updateListingInventory | Yes |
405
+ | ShopListing Offering | getListingOffering | No |
406
+ | ShopListing Product | getListingProduct | No |
407
+ | ShopListing Translation | createListingTranslation | No |
408
+ | ShopListing Translation | getListingTranslation | No |
409
+ | ShopListing Translation | updateListingTranslation | No |
410
+ | ShopListing VariationImage | getListingVariationImages | No |
411
+ | ShopListing VariationImage | updateVariationImages | No |
412
+ | ShopListing Video | deleteListingVideo | No |
413
+ | ShopListing Video | getListingVideo | No |
414
+ | ShopListing Video | getListingVideos | No |
415
+ | ShopListing Video | uploadListingVideo | No |
416
+ | Other | ping | No |
417
+ | Other | tokenScopes | No |
418
+ | Ledger Entry | getShopPaymentAccountLedgerEntry | Yes |
419
+ | Ledger Entry | getShopPaymentAccountLedgerEntries | Yes |
420
+ | Payment | getShopPaymentByReceiptId | No |
421
+ | Payment | getPaymentAccountLedgerEntry | No |
422
+ | Payment | getPayments | No |
423
+ | Shop Receipt | getShopReceipt | Yes |
424
+ | Shop Receipt | updateShopReceipt | Yes |
425
+ | Shop Receipt | getShopReceipts | Yes |
426
+ | Shop Receipt | searchAllShopReceipts | No |
427
+ | Shop Receipt Transactions | getShopReceiptTransaction | Yes |
428
+ | Shop Receipt Transactions | getShopReceiptTransactionsByListing | No |
429
+ | Shop Receipt Transactions | getShopReceiptTransactionsByReceipt | Yes |
430
+ | Shop Receipt Transactions | getShopReceiptTransactionsByShop | No |
431
+ | Review | getReviewsByListing | Yes |
432
+ | Review | getReviewsByShop | Yes |
433
+ | Shop HolidayPreferences | getShopHolidayPreferences | No |
434
+ | Shop HolidayPreferences | updateShopHolidayPreferences | No |
435
+ | Shop ProcessingProfiles | createShopShippingProfileUpgrade | No |
436
+ | Shop ProcessingProfiles | getShopShippingProfileUpgrades | Yes |
437
+ | Shop ProcessingProfiles | deleteShopShippingProfileUpgrade | No |
438
+ | Shop ProcessingProfiles | getShopShippingProfileUpgrade | No |
439
+ | Shop ProcessingProfiles | updateShopShippingProfileUpgrade | No |
440
+ | Shop ShippingProfile | getShippingCarriers | No |
441
+ | Shop ShippingProfile | createShopShippingProfile | Yes |
442
+ | Shop ShippingProfile | getShopShippingProfiles | Yes |
443
+ | Shop ShippingProfile | deleteShopShippingProfile | Yes |
444
+ | Shop ShippingProfile | getShopShippingProfile | Yes |
445
+ | Shop ShippingProfile | updateShopShippingProfile | Yes |
446
+ | Shop ShippingProfile | createShopShippingProfileDestination | Yes |
447
+ | Shop ShippingProfile | getShopShippingProfileDestinationsByShippingProfile | Yes |
448
+ | Shop ShippingProfile | deleteShopShippingProfileDestination | Yes |
449
+ | Shop ShippingProfile | updateShopShippingProfileDestination | Yes |
450
+ | Shop ShippingProfile | createShopShippingProfileUpgrade | No |
451
+ | Shop ShippingProfile | getShopShippingProfileUpgrades | Yes |
452
+ | Shop ShippingProfile | deleteShopShippingProfileUpgrade | No |
453
+ | Shop ShippingProfile | updateShopShippingProfileUpgrade | No |
454
+ | Shop | getShop | Yes |
455
+ | Shop | updateShop | Yes |
456
+ | Shop | getShopByOwnerUserId | Yes |
457
+ | Shop | findShops | No |
458
+ | Shop ProductionPartner | getShopProductionPartners | Yes |
459
+ | Shop Section | createShopSection | Yes |
460
+ | Shop Section | getShopSections | Yes |
461
+ | Shop Section | deleteShopSection | Yes |
462
+ | Shop Section | getShopSection | Yes |
463
+ | Shop Section | updateShopSection | Yes |
464
+ | Shop Return Policy | consolidateShopReturnPolicies | No |
465
+ | Shop Return Policy | createShopReturnPolicy | No |
466
+ | Shop Return Policy | getShopReturnPolicies | No |
467
+ | Shop Return Policy | deleteShopReturnPolicy | No |
468
+ | Shop Return Policy | getShopReturnPolicy | No |
469
+ | Shop Return Policy | updateShopReturnPolicy | No |
470
+ | User | getUser | Yes |
471
+ | User | getMe | No |
472
+ | UserAddress | deleteUserAddress | No |
473
+ | UserAddress | getUserAddress | No |
474
+ | UserAddress | getUserAddresses | No |
475
+
476
+ #### Review Methods
477
+ - `getReviewsByListing(listingId, options?)` - Get reviews for a listing
478
+ - `getReviewsByShop(shopId, options?)` - Get reviews for a shop
479
+
480
+ #### Search Methods
481
+ - `findAllListingsActive(params)` - Search listings with filters
474
482
 
475
483
  ### AuthHelper Methods
476
484
  - `getAuthUrl()` - Generate authorization URL
@@ -491,7 +499,7 @@ The package provides optimized builds for different environments:
491
499
  ```typescript
492
500
  interface EtsyClientConfig {
493
501
  keystring: string; // Required: Your API key
494
- sharedSecret?: string; // Your shared secret (from Your Apps page)
502
+ sharedSecret: string; // Required: Your shared secret (from Your Apps page)
495
503
  accessToken?: string; // User's access token
496
504
  refreshToken?: string; // User's refresh token
497
505
  expiresAt?: Date; // Token expiration date
@@ -832,4 +840,4 @@ If you have questions or need help:
832
840
 
833
841
  ## 🏷️ Changelog
834
842
 
835
- See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
843
+ See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.