@profplum700/etsy-v3-api-client 3.0.1 → 4.1.0

package/CHANGELOG.md

@@ -1,4 +1,24 @@
 # Changelog
+
+## 4.1.0
+
+### Minor Changes
+
+- f285f3f: Add an `enableScaleValidation` option to `updateListingInventory`, sent as Etsy's temporary `enable_scale_validation` query parameter. Etsy makes scale validation mandatory on 1 January 2027; opting in now surfaces payloads whose scaled properties lack a valid, consistent `scale_id`.
+
+## 4.0.0
+
+### Major Changes
+
+- a147325: Keep partial rate-limit settings from erasing retry defaults, track the QPD fallback over a rolling 24-hour window, serialize concurrent request reservations, honor Etsy's shared Retry-After cooldown, avoid automatically replaying mutations, and align inventory update inputs with Etsy's accepted request fields.
+
+### Minor Changes
+
+- a147325: Add an async token refresh persistence callback that the client awaits before exposing refreshed tokens. Keep the existing synchronous callback type unchanged.
+
+### Patch Changes
+
+- a147325: Retry persistence of Etsy-rotated tokens without repeating OAuth refresh, fence refresh persistence against concurrent token updates or clears, preserve legacy synchronous `refreshSave` clearing behavior while requiring a paired clear callback for new async persistence, preserve quota-probe response identity for safe exhausted-quota recovery (custom transports must migrate from uncorrelated `updateFromHeaders` calls to the reservation-aware API), keep active-listing pagination metadata within its accepted offset limit, accept listing IDs returned by the list tool, page large inventory results, validate local OAuth callback addresses, verify same-listing price targets from one final inventory snapshot, and include required `property_values` in non-variation inventory examples.
 
 All notable changes to this project will be documented in this file.
 

package/README.md

@@ -33,7 +33,23 @@ yarn add @profplum700/etsy-v3-api-client
 pnpm add @profplum700/etsy-v3-api-client
 ```
 
-## 🔧 Quick Start
+## 🤖 Connect an agent to your Etsy shop
+
+The companion [`@profplum700/etsy-mcp-server`](packages/etsy-mcp-server/README.md) package runs locally over stdio and exposes read-only shop, active-listing, and listing-inventory tools. It requires Node.js 24+, your own approved Etsy developer app, and an OS credential store. It does not use a hosted endpoint.
+
+Register `http://localhost:3030/oauth/redirect` as the Etsy app callback if required, then run this in a local interactive terminal:
+
+```bash
+npx --yes @profplum700/etsy-mcp-server@latest setup
+```
+
+Enter your keystring and shared secret in the hidden terminal prompts, authorize only `shops_r` and `listings_r` in Etsy, then choose whether to add the server to your user-level Codex MCP configuration. For another stdio client, configure `npx --yes @profplum700/etsy-mcp-server@latest serve` as its launch command.
+
+You can connect multiple shops without replacing earlier profiles. Run `setup --reuse-app --manual-browser` to reuse the saved developer app credentials, then open the printed authorization URL in the browser profile signed in to the shop you want to add. Use `status` to see saved shops and `use <shop name or ID>` to choose which one MCP tools query. `disconnect` removes only the active shop; `disconnect --all` removes every saved profile. Use `remove-codex` to remove the Codex entry without disconnecting any shop.
+
+**Prompt for an agent:** “Set up the local Etsy MCP server. Do not ask me to paste Etsy credentials into chat or save them in a repository or environment file. Run the setup command in an interactive local terminal so I can enter them there; request only `shops_r` and `listings_r`, verify my shop, and offer the user-level Codex connection.”
+
+## 🔧 Quick Start
 
 ### Basic Setup
 
@@ -173,7 +189,7 @@ const client = new EtsyClient({
   rateLimiting: {
     enabled: true,
     maxRequestsPerSecond: 5,
-    maxRequestsPerDay: 5000
+    maxRequestsPerDay: 5000 // Conservative local fallback; Etsy response headers report this app's actual quota
   },
   caching: {
     enabled: true,
@@ -292,18 +308,34 @@ const client = new EtsyClient({
   // ... other config
   rateLimiting: {
     enabled: true,
-    maxRequestsPerSecond: 5,     // Requests per second (Etsy's limit)
-    maxRequestsPerDay: 5000,     // Requests per day (Etsy's limit)
-    minRequestInterval: 200      // Minimum ms between requests (1000 / 5 QPS)
+    maxRequestsPerSecond: 5,     // Conservative QPS fallback
+    maxRequestsPerDay: 5000,     // Conservative rolling 24-hour fallback
+    minRequestInterval: 200      // Minimum ms between requests (5 QPS fallback)
   }
 });
 
-// Check remaining requests
-const remaining = client.getRemainingRequests();
-console.log(`${remaining} requests remaining today`);
-```
-
-## 🔄 Caching
+// Check remaining requests in the rolling local window
+const remaining = client.getRemainingRequests();
+console.log(`${remaining} requests remaining in the rolling 24-hour window`);
+```
+
+When building a custom transport around the exported `EtsyRateLimiter`, keep the reservation ID attached to its response so concurrent, out-of-order headers cannot incorrectly restore exhausted quota:
+
+```typescript
+const reservationId = await rateLimiter.waitForRateLimitWithReservation();
+let response: Response;
+try {
+  response = await fetch(url);
+} catch (error) {
+  rateLimiter.releaseRequestSlot(reservationId);
+  throw error;
+}
+rateLimiter.updateFromHeaders(response.headers, reservationId);
+```
+
+`waitForRateLimit()` remains available for source compatibility when you only need dispatch pacing. For custom transports that also feed response headers back to the limiter, use the reservation-aware method above; uncorrelated positive headers cannot safely reopen exhausted quota.
+
+## 🔄 Caching
 
 Optional response caching to improve performance: