feat: V2 API support, new tools, and API docs#21
Merged
jack-arturo merged 3 commits intoverygoodplugins:mainfrom Feb 18, 2026
Merged
feat: V2 API support, new tools, and API docs#21jack-arturo merged 3 commits intoverygoodplugins:mainfrom
jack-arturo merged 3 commits intoverygoodplugins:mainfrom
Conversation
Upgrade products and customers endpoints to always use V2 API, which returns richer data (sku, category/tag objects, date_created, additional_emails) while remaining fully backward-compatible with V1 responses. ## V2 API migration - Products: always use V2 with search, category, and tag filtering; normalize both array and numeric-keyed object responses - Customers: always use V2 with date preset and date range filtering; use `&customer=` param for single lookups (accepts ID or email) - Add `buildV2Url()` for V2 endpoint construction - Remove `buildPublicUrl()` (V2 with auth is always used) ## New tools - `edd_get_discount_by_code` — case-insensitive lookup by discount code - `edd_list_active_discounts` — filter to only active discount codes - `edd_get_stats_by_preset` — stats with date presets (today, this_week, this_quarter, this_year, etc.) ## Schema improvements - `ProductInfoSchema`: add `sku`, widen `category`/`tags` to accept V2 object arrays, widen `exp_length` to accept string - `ProductSchema`: add `index` and `attachment_id` to file objects - `ProductsResponseSchema`: accept both array and numeric-keyed object - `CustomerInfoSchema`: make `id` optional (V2 returns `customer_id`), add `additional_emails` and `date_created` - Add input schemas for all new tools with date pair validation ## Resilience - Treat EDD "No X found!" API responses as empty results, not errors - Gracefully handle V2 numeric-keyed product objects (Object.values) - Validate startDate/endDate pairs in customer listing tool ## Documentation - Add docs/API.md with complete tool reference, response formats, date presets, and API version details ## Tests - 40 unit tests covering V2 URL construction, response normalization, date filtering, search/category/tag params, discount by code, active discount filtering, stats presets, and empty result handling Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughMigrates the client and tools to use the EDD V2 API, adds V2-aware methods for products, customers, discounts, and stats (including response normalization and client-side filters), introduces comprehensive API docs, updates types, and expands unit tests and tool signatures for new inputs. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
src/edd-client.ts (4)
243-263:buildV2Urlis defined after its first call site — consider reordering for readability.
buildV2Url(line 246) is called on line 226 but defined aftergetProduct. While method ordering within a class is not a runtime issue in TypeScript, placing private helpers before their first use improves readability.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/edd-client.ts` around lines 243 - 263, The private helper buildV2Url is defined after its first call in getProduct; move the buildV2Url method so it appears before the first usage (i.e., place buildV2Url above getProduct or any other method that calls it) to improve readability; ensure you preserve the existing signature and behavior (private buildV2Url(endpoint: string, params: Record<string, string|number|undefined> = {}): string) and update nothing else in getProduct or callers.
525-536:getDiscountByCodefetches all discounts on every call — document or mitigate the cost.Passing
number: -1fetches the entire discount list from the API on every invocation. For stores with many discounts, this could be slow and bandwidth-heavy. The JSDoc is clear about this, which is good. Consider caching discounts or at least noting this in the API docs.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/edd-client.ts` around lines 525 - 536, getDiscountByCode currently calls listDiscounts({ number: -1 }) on every invocation which forces fetching the entire discount list; update the implementation and docs to avoid repeated full-list fetches by either: 1) adding a simple in-memory cache inside the EddClient class keyed by store and invalidated on discount mutations (use getDiscountByCode to consult the cache first and fall back to listDiscounts then populate cache), or 2) adding an optional parameter to getDiscountByCode like useCache?: boolean or maxFetch?: number so callers can opt into cached lookups or limit results; also update the JSDoc for getDiscountByCode and mention listDiscounts usage and cache behavior so callers know the cost.
484-501:getStatsByPresetlargely duplicatesgetStats— consider consolidating.The response normalization logic in
getStatsByPreset(lines 494-500) is identical togetStats(lines 374-382). You could havegetStatsaccept an optionaldateparameter and reuse it, or extract the normalization into a shared helper.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/edd-client.ts` around lines 484 - 501, Consolidate duplicate response-normalization between getStatsByPreset and getStats by either adding an optional date parameter to getStats (e.g., change getStats(type: 'sales'|'earnings', date?: string)) and have getStats build the URL via this.buildUrl('stats/', { type, date }) and call this.request, or extract the normalization logic into a shared helper (e.g., normalizeStatsResponse(response): StatsResponse['stats']) and have both getStats and getStatsByPreset call that helper; update getStatsByPreset to delegate to the unified getStats or the helper so the duplicated block (the "if ('stats' in response ... return { [type]: response[type] }") is removed and only one place handles normalization.
182-185: Good resilience: "No X found!" treated as empty results.The regex
/^No \w+ found!?$/icorrectly matches EDD empty-result messages like "No customers found!". However, the pattern is limited to single-word entity names (e.g.,customers,products). If EDD returns error messages with multi-word entity names (e.g., "No download logs found!"), the regex would fail to match due to the space. Consider updating to/^No [\w\s]+ found!?$/iif broader compatibility is desired, though current test coverage only demonstrates single-word entities.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/edd-client.ts` around lines 182 - 185, The current check on data.error uses a regex that only matches a single-word entity after "No" so multi-word messages like "No download logs found!" slip through; update the regex used in the data.error conditional to allow whitespace inside the entity name (i.e., allow one-or-more word-or-space characters after "No") so those messages are treated as empty results, keep the existing throw new Error(...) behavior for true errors, and update/add tests covering multi-word entity messages; refer to the data.error check and the throw new Error(...) line in src/edd-client.ts when making the change.src/types.ts (1)
309-329: Import V2 input schemas in index.ts instead of duplicating them inline.
GetDiscountByCodeInputSchema,ListActiveDiscountsInputSchema, andGetStatsByPresetInputSchemaare exported from src/types.ts but not referenced anywhere. Tools 14, 16, and 17 in src/index.ts define equivalent inline Zod schemas instead of importing these definitions. Import and use the schemas from types.ts to avoid duplication and maintain consistency with the coding guideline for Zod schema usage in src/**/*.ts files.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/types.ts` around lines 309 - 329, Replace the duplicated inline Zod schemas used by the tool definitions in src/index.ts (the schemas defined for tools 14, 16, and 17) with the exported schemas from src/types.ts: import GetDiscountByCodeInputSchema, ListActiveDiscountsInputSchema, and GetStatsByPresetInputSchema and use those in the corresponding tool input definitions instead of recreating them inline so the tools reference the single source-of-truth schema names (GetDiscountByCodeInputSchema, ListActiveDiscountsInputSchema, GetStatsByPresetInputSchema).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/API.md`:
- Around line 549-551: The docs line claiming "retries failed requests up to 3
times" is misleading because edd-client.ts uses retries = 3 with the loop
condition "attempt <= retries", resulting in 3 total attempts (initial attempt +
2 retries); update the API docs wording to clarify this by changing the sentence
to something like "The server will attempt failed requests up to 3 attempts
total (initial attempt plus 2 retries) with exponential backoff (1s, 2s, 4s)" so
it matches the behavior of the retries variable and the attempt <= retries
check.
In `@src/index.ts`:
- Around line 573-574: The tool comment numbering is inconsistent (skipping
"Tool 15"); locate the block comments labeled "Tool 14", "Tool 16: List Active
Discounts", and "Tool 17" in src/index.ts and renumber them sequentially (e.g.,
change "Tool 16" -> "Tool 15" and "Tool 17" -> "Tool 16" or adjust all
subsequent tool comment labels) so the comment headings match the actual order
of tools and avoid the missing "Tool 15" gap.
---
Nitpick comments:
In `@src/edd-client.ts`:
- Around line 243-263: The private helper buildV2Url is defined after its first
call in getProduct; move the buildV2Url method so it appears before the first
usage (i.e., place buildV2Url above getProduct or any other method that calls
it) to improve readability; ensure you preserve the existing signature and
behavior (private buildV2Url(endpoint: string, params: Record<string,
string|number|undefined> = {}): string) and update nothing else in getProduct or
callers.
- Around line 525-536: getDiscountByCode currently calls listDiscounts({ number:
-1 }) on every invocation which forces fetching the entire discount list; update
the implementation and docs to avoid repeated full-list fetches by either: 1)
adding a simple in-memory cache inside the EddClient class keyed by store and
invalidated on discount mutations (use getDiscountByCode to consult the cache
first and fall back to listDiscounts then populate cache), or 2) adding an
optional parameter to getDiscountByCode like useCache?: boolean or maxFetch?:
number so callers can opt into cached lookups or limit results; also update the
JSDoc for getDiscountByCode and mention listDiscounts usage and cache behavior
so callers know the cost.
- Around line 484-501: Consolidate duplicate response-normalization between
getStatsByPreset and getStats by either adding an optional date parameter to
getStats (e.g., change getStats(type: 'sales'|'earnings', date?: string)) and
have getStats build the URL via this.buildUrl('stats/', { type, date }) and call
this.request, or extract the normalization logic into a shared helper (e.g.,
normalizeStatsResponse(response): StatsResponse['stats']) and have both getStats
and getStatsByPreset call that helper; update getStatsByPreset to delegate to
the unified getStats or the helper so the duplicated block (the "if ('stats' in
response ... return { [type]: response[type] }") is removed and only one place
handles normalization.
- Around line 182-185: The current check on data.error uses a regex that only
matches a single-word entity after "No" so multi-word messages like "No download
logs found!" slip through; update the regex used in the data.error conditional
to allow whitespace inside the entity name (i.e., allow one-or-more
word-or-space characters after "No") so those messages are treated as empty
results, keep the existing throw new Error(...) behavior for true errors, and
update/add tests covering multi-word entity messages; refer to the data.error
check and the throw new Error(...) line in src/edd-client.ts when making the
change.
In `@src/types.ts`:
- Around line 309-329: Replace the duplicated inline Zod schemas used by the
tool definitions in src/index.ts (the schemas defined for tools 14, 16, and 17)
with the exported schemas from src/types.ts: import
GetDiscountByCodeInputSchema, ListActiveDiscountsInputSchema, and
GetStatsByPresetInputSchema and use those in the corresponding tool input
definitions instead of recreating them inline so the tools reference the single
source-of-truth schema names (GetDiscountByCodeInputSchema,
ListActiveDiscountsInputSchema, GetStatsByPresetInputSchema).
- Fix retry docs: clarify "3 total attempts" not "retries 3 times" - Fix tool numbering: 14 → 15 → 16 (was skipping 15) - Move buildV2Url above first call site for readability - Consolidate getStatsByPreset into getStats(type, date?) with shared normalizeStatsResponse helper to eliminate duplication - Widen "No X found!" regex to handle multi-word entities like "No download logs found!" via [\w\s]+ - Add test for multi-word empty-result messages (41 tests total) Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
src/edd-client.ts (1)
205-222:buildV2Urlduplicates the auth and param-iteration logic frombuildUrlAuth token assignment and the
Object.entriesloop are identical in both methods. This is an optional DRY cleanup—either compute the v2 base URL and delegate tobuildUrl, or accept aversionargument.♻️ Suggested refactor
- private buildV2Url(endpoint: string, params: Record<string, string | number | undefined> = {}): string { - const base = this.apiUrl.replace(/\/$/, ''); - const v2Base = `${base}/v2/`; - const url = new URL(endpoint, v2Base); - - url.searchParams.set('key', this.apiKey); - url.searchParams.set('token', this.apiToken); - - for (const [key, value] of Object.entries(params)) { - if (value !== undefined) { - url.searchParams.set(key, String(value)); - } - } - - return url.toString(); - } + private buildV2Url(endpoint: string, params: Record<string, string | number | undefined> = {}): string { + const base = this.apiUrl.replace(/\/$/, ''); + const v2Base = `${base}/v2/`; + // Temporarily override apiUrl so buildUrl resolves against the V2 base + const saved = this.apiUrl; + // Alternatively, inline and reuse buildUrl with a modified base via a private helper + return this.buildUrl(endpoint, params, v2Base); + }Or extract a single private
buildUrlWithBase(base, endpoint, params)helper that bothbuildUrlandbuildV2Urldelegate to.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/edd-client.ts` around lines 205 - 222, buildV2Url duplicates authentication and param-iteration logic already present in buildUrl; refactor to remove duplication by creating a shared helper or delegating: either add an optional version parameter to buildUrl or implement a private helper like buildUrlWithBase(base, endpoint, params) and have both buildUrl and buildV2Url call that helper (move the base construction for v2 into the helper or compute v2Base in buildV2Url and pass it to buildUrlWithBase), ensuring auth (this.apiKey/this.apiToken) and the Object.entries params loop are only implemented once.tests/unit/edd-client.test.ts (1)
659-677:normalizeStatsResponsedirect-format branch is not coveredAll
getStatstest cases — including the new preset test — mock the wrapped{ stats: { ... } }format. The fallback branch innormalizeStatsResponse(lines 488-489 inedd-client.ts):return { [type]: response[type] } as StatsResponse['stats'];has no test coverage. If the EDD API ever returns data directly (as the coding guideline suggests it should), this path would be exercised in production but never in CI.
✅ Suggested test to add
it('should handle direct (unwrapped) stats response format', async () => { mockFetch.mockResolvedValueOnce({ ok: true, json: async () => ({ earnings: { current_month: 3000, last_month: 2500, totals: 50000 }, request_speed: 0.01, }), }); const stats = await client.getStats('earnings'); expect(stats.earnings?.current_month).toBe(3000); expect(stats.earnings?.totals).toBe(50000); });🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/unit/edd-client.test.ts` around lines 659 - 677, Add a unit test exercising the direct (unwrapped) response path in normalizeStatsResponse by mocking fetch to return a JSON object that contains the stats fields at the top level (e.g., { earnings: { current_month: 3000, totals: 50000 }, request_speed: 0.01 }) instead of wrapped under { stats: {...} }, then call client.getStats('earnings') and assert the returned stats (for example that stats.earnings.current_month === 3000 and stats.earnings.totals === 50000) so the fallback branch in normalizeStatsResponse is covered; reference the existing test scaffold (mockFetch, client.getStats, and normalizeStatsResponse) and add this new it(...) case alongside the other getStats tests.src/index.ts (1)
213-222: MovestartDate/endDatepair validation to Zod schemaPer the coding guideline to use Zod schemas for input validation, the pair constraint should move from the handler to the input schema. MCP SDK v1.25.1's
registerTool()accepts fullZodObjectinstances with.refine():Schema-level validation using
z.object().refine()- inputSchema: { - number: z.number().optional().describe('Number of customers to return (default: 10)'), - page: z.number().optional().describe('Page number for pagination'), - date: z.enum(['today', 'yesterday']).optional().describe('Filter by creation date preset'), - startDate: z.string().optional().describe('Start date in YYYYMMDD format (requires endDate)'), - endDate: z.string().optional().describe('End date in YYYYMMDD format (requires startDate)'), - }, + inputSchema: z.object({ + number: z.number().optional().describe('Number of customers to return (default: 10)'), + page: z.number().optional().describe('Page number for pagination'), + date: z.enum(['today', 'yesterday']).optional().describe('Filter by creation date preset'), + startDate: z.string().optional().describe('Start date in YYYYMMDD format (requires endDate)'), + endDate: z.string().optional().describe('End date in YYYYMMDD format (requires startDate)'), + }).refine( + (data) => !(data.startDate && !data.endDate) && !(!data.startDate && data.endDate), + { message: 'Both startDate and endDate are required when using date range filtering' } + ),Remove the handler-level validation at lines 218–222 once the schema-level check is in place.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/index.ts` around lines 213 - 222, Add the startDate/endDate pair constraint into the Zod input schema by updating the z.object that defines startDate and endDate to include .refine(data => (data.startDate && data.endDate) || (!data.startDate && !data.endDate), { message: 'Both startDate and endDate are required when using date range filtering', path: ['startDate'] }) (or similar path), then remove the runtime check inside the handler async ({ number, page, date, startDate, endDate }) => that returns the error when only one date is provided; keep the schema-level validation and rely on registerTool() to surface validation errors.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/API.md`:
- Around line 549-551: The documented exponential backoff sequence is incorrect
for the described retry logic: with "retries = 3" and loop condition "attempt <=
retries" you only get two waits (1s after attempt 1 and 2s after attempt 2), so
change the docs or the control variables to match; either update the text under
"Retry Logic" to state the delays are (1s, 2s) for 3 total attempts, or if you
intend (1s, 2s, 4s) make the code use four attempts (e.g., set retries = 4 or
adjust the loop condition) so the backoff formula 2^(n-1)*1s produces 1s, 2s,
4s.
In `@src/edd-client.ts`:
- Around line 481-490: The normalizeStatsResponse function contains an
unreachable branch checking for a top-level "stats" wrapper; remove that branch
and simplify the implementation so it always returns the direct response shape
expected by the EDD API (i.e., return { [type]: response[type] } as
StatsResponse['stats']). Update normalizeStatsResponse to mirror how
getStatsByDateRange and getStatsByProduct handle the API response, ensuring no
"stats" wrapper logic remains.
---
Nitpick comments:
In `@src/edd-client.ts`:
- Around line 205-222: buildV2Url duplicates authentication and param-iteration
logic already present in buildUrl; refactor to remove duplication by creating a
shared helper or delegating: either add an optional version parameter to
buildUrl or implement a private helper like buildUrlWithBase(base, endpoint,
params) and have both buildUrl and buildV2Url call that helper (move the base
construction for v2 into the helper or compute v2Base in buildV2Url and pass it
to buildUrlWithBase), ensuring auth (this.apiKey/this.apiToken) and the
Object.entries params loop are only implemented once.
In `@src/index.ts`:
- Around line 213-222: Add the startDate/endDate pair constraint into the Zod
input schema by updating the z.object that defines startDate and endDate to
include .refine(data => (data.startDate && data.endDate) || (!data.startDate &&
!data.endDate), { message: 'Both startDate and endDate are required when using
date range filtering', path: ['startDate'] }) (or similar path), then remove the
runtime check inside the handler async ({ number, page, date, startDate, endDate
}) => that returns the error when only one date is provided; keep the
schema-level validation and rely on registerTool() to surface validation errors.
In `@tests/unit/edd-client.test.ts`:
- Around line 659-677: Add a unit test exercising the direct (unwrapped)
response path in normalizeStatsResponse by mocking fetch to return a JSON object
that contains the stats fields at the top level (e.g., { earnings: {
current_month: 3000, totals: 50000 }, request_speed: 0.01 }) instead of wrapped
under { stats: {...} }, then call client.getStats('earnings') and assert the
returned stats (for example that stats.earnings.current_month === 3000 and
stats.earnings.totals === 50000) so the fallback branch in
normalizeStatsResponse is covered; reference the existing test scaffold
(mockFetch, client.getStats, and normalizeStatsResponse) and add this new
it(...) case alongside the other getStats tests.
- Fix backoff docs: only 2 delays occur (1s, 2s), not 3 — third
attempt either succeeds or throws
- Remove dead stats wrapper check from normalizeStatsResponse — EDD
API returns stats directly ({ earnings: {...} }), never wrapped
- Update test mocks to match real EDD API response format
Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR upgrades the MCP EDD server to use V2 API endpoints for products and customers, adds three new read-only tools, improves schema resilience, and includes comprehensive API documentation.
Tested against live EDD stores (GravityKit, WP Fusion, Barn2) to validate V2 behavior across different configurations.
V2 API migration
sku, richercategory/tags(object arrays), and server-sidesearch,category, andtagfiltering. Normalizes both standard arrays and numeric-keyed object responses.date_created,additional_emails, date preset filtering (today/yesterday), date range filtering (YYYYMMDD), and unified&customer=param for single lookups by ID or email.V2 is a strict superset of V1 — no functionality is lost.
New tools
edd_get_discount_by_codeedd_list_active_discountsedd_get_stats_by_presettoday,this_week,this_quarter,this_year, etc.)Schema improvements
ProductInfoSchema: addsku; widencategory/tagsfor V2 object arraysProductsResponseSchema: accept both array and numeric-keyed objectCustomerInfoSchema:idnow optional (V2 returnscustomer_id); addadditional_emails,date_createdindexandattachment_idfieldsexp_length: accept both number and stringResilience fixes
Object.values()startDate/endDatepair validation in customer listing toolDocumentation
docs/API.md— complete tool reference with response formats, date presets, and API version detailsTest plan
npm run buildcompiles cleanlynpm test— 40 unit tests pass (was 26, added 14)npm run lint— no errorsclass-edd-api.php)