ggcheckout-mcp 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,203 @@ which is unpinned — a new version reaches every existing installation on its n
 Read this file before upgrading, and pin a version if a breaking change is not convenient
 right now.
 
+## 0.4.0
+
+Checked end to end against a QA account on the Postgres (v2) data path, and product edits
+also against production.
+
+### Release requirement — do not publish before the API has these changes
+
+Two tools depend on an open pull request of the API. Published before it, the install (unpinned)
+reaches everyone, and they write a model the API does not read yet:
+
+- `set_offer_product_page` and `get_offer_snippets` need the per-product seller page model of
+  ggCheckout/saas-checkout#1681 (`productOverrides[product].displayMode` + `externalFlow.pageUrl`).
+  Against an API without it, the write is saved but the buyer never reaches the seller's page.
+
+`update_module`, `update_section`, `update_lesson`, `delete_module`, `delete_section` and
+`delete_lesson` need the `PATCH`/`DELETE` routes under `/api/members-area/{areaId}/modules/…` of
+ggCheckout/saas-checkout#1685, merged on 2026-10-13. Against an API without them they answer
+"this API has no such route yet", not as a missing item.
+
+### Breaking
+
+Every item here changes what an existing call sends or gets back. A 0.x minor bump is a
+breaking release, and with the unpinned install it reaches everyone on the next start.
+
+- **`list_rewards` is gone; use `calculate_rewards`.** The route it called was removed along
+  with the stored counter it served. `calculate_rewards` answers the same fields, derived from
+  paid sales, and carries the milestone list — there is no reward catalogue endpoint.
+  `currentRevenue` and `milestones` are in reais, not cents.
+- **`upload_deliverable` takes `fileSize` and no longer takes `fileUrl`**, and attaching is now
+  two calls: `upload_deliverable` mints an upload URL, you PUT the bytes to it, and
+  **`attach_deliverable`** confirms the upload and links it. See "Routes that had moved".
+- **`reorder_upsells` takes `upsellIds`** (all the ids, in order) instead of `upsells` (whole
+  objects). Both reorder tools now return the resulting positions.
+- **`add_credit` answers a new shape** — `{ creditId, amountCents, pixCode, pixQrBase64,
+  expiresAt, via }` — and **`amountCents` must be whole cents from 325 to 25000** (R$ 3,25 to
+  R$ 250,00). Anything else used to reach the API; it is now refused before the call.
+- **`create_webhook` / `update_webhook` accept only the 15 real event names**, and
+  **`test_webhook` simulates only `pix.paid`, `card.paid`, `pix.expired`, `card.expired`**. The
+  old suggestions (`payment.created`, `payment.paid`, `payment.refunded`…) are refused.
+- **`insert_token` takes `type` and `target` from `pushinpay`, `utmify`, `emailprovider`,
+  `mercadopago`.** Any other value was always refused by the API.
+- **Lower caps:** `get_payments_paginated` `pageSize` 1000 → 100 (the API already reduced it
+  silently); `list_credits` `limit` 1000 → 200, the lowest cap of the two statements it reads.
+- **`update_funnel` no longer takes `settings.pixels` or `settings.webhookUrl`.** Nothing
+  read them: the quiz page resolves `settings.pixelTokenIds` (ids from `list_tokens`) and
+  webhooks are `settings.webhookIds` (ids from `list_webhooks`). A call that still sends
+  them is refused by validation instead of being silently ignored.
+- **`list_products` hides deleted products.** `delete_product` is a soft delete and the API
+  keeps listing the row with `deleted: true`.
+- `list_store_products` no longer accepts `sortBy: "createdAt"` (the API ignored it), and
+  `validate_coupon` takes `orderValue` as integer cents.
+- **`update_checkout` merges the `checkout` object instead of replacing it.** Send only the keys
+  to change. An array still replaces the stored one, and a key can no longer be removed by leaving
+  it out; set it to `null` instead. The stored `checkout.paymentMethods` is not part of the merge:
+  the read does not return every stored value of the methods, so re-sending it could rewrite them
+  with less than what is stored. Payment methods change only when the call sends them.
+- **`upload_deliverable` requires `fileType`.**
+- **Empty lists are refused** where the API would do nothing with them: `events` in
+  `create_webhook` / `update_webhook` and `order` in `reorder_downsells` need at least one item.
+- **Lesson `content` follows the API's shape** (`create_lesson`, `update_lesson`). Quiz questions
+  are `{ id, question, type, options: string[], correctAnswer, explanation, points }`; the old
+  `{ text, options: [{ id, text, isCorrect }] }` was stored as sent and no student could be graded
+  on it. `textMarkdown`, `videoId`, `videoDuration`, `videoThumbnail`, `videoQualities`,
+  `estimatedReadTime`, `fileSize` and `fileType` are gone: the API dropped them with a 200. URLs
+  must be absolute, at most 50 questions, `minScore` a whole number from 0 to 100.
+- **Cascading deletes need `confirm: true`** (`delete_module`, `delete_section`, `delete_lesson`).
+
+### Routes that had moved
+
+A sweep of every endpoint this client calls against the current API found four with no route
+behind them any more, plus a set of tools whose behaviour had drifted. Each item below was
+confirmed in the API source, and the fixes were exercised against a live account.
+
+- **`list_rewards` → `calculate_rewards`** (see Breaking).
+- **`add_credit` works on both billing generations.** The legacy route refuses a migrated
+  seller with 409 pointing at the top-up route; the call now follows that refusal, and only
+  that one. Takes an optional `idempotencyKey`, which only the new billing reads. A timeout or
+  a 502 may still have opened the PIX, so that error now says to look in `list_credits` before
+  retrying instead of inviting a second charge.
+- **`list_credits` returns the statement for either generation.** It reads the legacy credits
+  and the credit ledger, and answers `{ credits, total, ledger: { entries, nextBefore } }`. One
+  side is empty depending on the account, which is the true answer and not an error — before
+  this, a migrated seller got an empty list with no indication the data lived elsewhere. If one
+  side fails, the other still answers and `creditsError` / `ledgerError` says what failed.
+- **`upload_deliverable` / `delete_deliverable` now call routes that exist.** The paths they
+  used (`/api/products/{id}/deliverable/…`) are not part of the API. Attaching a file is now
+  two steps: `upload_deliverable` mints an upload URL, you PUT the bytes to it (only
+  `Content-Type`, no `Authorization`), then **`attach_deliverable`** confirms the upload and
+  links it to the product, keeping any link the product already has. `delete_deliverable`
+  unlinks the file and, given `filePath`, deletes the bytes too; it refuses when the file is
+  the only deliverable, and a failed byte deletion comes back as `fileDeleteError` beside the
+  completed unlink.
+- **`telegram_media_upload` calls `/presign`.** The old path was renamed. It returns
+  `{ uploadUrl, filePath, proxyUrl }`; `proxyUrl` is the URL to store in the flow node, because
+  the route does not return a public URL. The previously advertised `publicUrl` was always
+  undefined.
+- **`reorder_upsells` calls `.../upsells/reorder`.** It used to send whole objects to a route
+  that replaces the legacy upsell array instead of reordering, and that route does not exist
+  for a product on the new storage, where the call failed as an opaque 502.
+- **`update_product` writes the way each storage expects.** It used to re-send the whole
+  stored product. That is still what the old storage needs — its write puts a default into
+  every key the body omits (`url: ''`, `deliverableFile: null`, `membersAreaEnabled: false`…),
+  so a partial body would wipe the product with a 200 — and its read carries the file and the
+  stock lines, so it still goes back whole (minus the live `stockQuantity`). On the new storage
+  the read carries neither, so the re-send dropped them and the save was refused; there the
+  call now sends the edit plus the one field that satisfies the API's deliverable check (the
+  check reads the request body, not the stored product). When the only deliverable is a file or
+  stock lines — neither readable there — the edit is refused here with an explanation instead
+  of a bare 400. `attach_deliverable` and `delete_deliverable` go through the same write.
+- **`create_webhook` / `update_webhook` validate `events`.** The API stores event names without
+  checking them and dispatch matches exactly, so a wrong name is accepted and never fires. The
+  names this tool used to suggest (`payment.created`, `payment.paid`, `payment.refunded`) are
+  not seller webhook events at all. The real vocabulary is now enforced here, and `test_webhook`
+  simulates only the payment-shaped events.
+- **`insert_token` accepts only the four types the API takes**, in `type` and in `target`,
+  which the route checks against the same list. `stripe` and `efibank` were advertised and
+  always refused.
+- **`list_payments` answers an empty list for a seller with no sales.** The route reports that
+  state as 404, which surfaced as an error.
+- **`get_payments_paginated`**: the cursor in the answer is `nextCursor`; `totalCapped: true`
+  means the count stopped at its cap and `total` is a floor; a text search may come back with
+  `coverageCapped`.
+- **423 is not a thing, 503 is not "the backend is down".** 503 means the rate limiter is
+  failing closed and nothing was changed, so it is reported as retryable. 502 means the service
+  behind the API did not answer, and a write may or may not have landed, so it says to check
+  before repeating one. The wait is read from `Retry-After` or the body's `retry_after`. A
+  refusal that carries a `code` now shows it instead of just a status number.
+
+### Tools that an API key cannot use
+
+`create_whatsapp_session` answers 403 for an API key by design: the route classes it as
+sensitive. It now says so and what to do instead, rather than surfacing a bare "Forbidden".
+
+### Packaging
+
+- Compiled tests no longer ship in the published package (560 files down to 428).
+- `dotenv` is loaded quietly: version 17 announces itself on stdout, which is the MCP protocol
+  channel over stdio, and a strict client reads that line as a malformed frame.
+
+### Added
+
+- **Offers on the seller's page:** `set_offer_product_page` puts one product of an upsell or
+  downsell on the seller's own page (or back on the GG page), mixed with GG pages in the same
+  funnel; `get_offer_snippets` returns, read only, the HTML to paste for each product on the
+  seller's page. `update_checkout` now merges the `checkout` object, so setting one key keeps the
+  rest of the page setup.
+- **Members-area files:** `upload_members_area_file` uploads an image, a lesson video or a file
+  (PDF, document, audio) from the machine running the server and returns the URL to use. It reads
+  only from the folder set in `GGCHECKOUT_UPLOAD_ROOT` and refuses every upload while that is unset.
+  `create_pdf_lessons` creates a batch of PDF lessons; `list_lesson_attachments`,
+  `add_lesson_attachment` and `delete_lesson_attachment` manage a lesson's complementary files.
+- **Editing and deleting the course structure:** `update_module`, `update_section`, `update_lesson`,
+  `delete_module`, `delete_section`, `delete_lesson` — until now only the dashboard could, through
+  server actions an API key cannot call. **They need the API release with the `PATCH`/`DELETE`
+  routes under `/api/members-area/{areaId}/modules/…`**; an older deployment answers 404/405.
+- `create_module` and `create_section` take `dripSettings`; `create_section` and `create_lesson`
+  take `showTitleOverlay`, `showImageOnly` and `order`, and `create_lesson` a `thumbnailUrl`.
+- `list_stores`, the only way to get the `storeId` every store tool takes. It also returns
+  DELETED stores — the listing it comes from never filtered them and the API does not mark
+  them — and such a storeId answers 404 in every other store tool, so the description now
+  warns to confirm an unfamiliar one with `get_store`.
+- Store management: `create_store`, `get_store`, `update_store`, `delete_store`, store
+  categories (`list_store_categories`, `create_store_category`, `update_store_category`,
+  `delete_store_category`) and review moderation (`list_store_reviews`,
+  `create_store_review`, `update_store_review`, `delete_store_review`). **These need the
+  `/api/stores/{storeId}` routes**, available from the GG Checkout release that ships them;
+  against an older deployment they answer 404/405.
+- Store builder: `get_store_layout`, `update_store_layout`, `publish_store_layout`,
+  `list_store_layout_history`, `restore_store_layout_version`, `get_store_theme`. A store with
+  no layout yet — which is every newly created one — has nothing to copy the block shapes
+  from, and the route validates them strictly, so the first-save error now spells out an
+  accepted `theme` and block shape.
+- `list_funnel_checkouts`: the checkouts and gateways a funnel `pix` component can use.
+- `update_product` takes `stockEnabled`, `unlimitedStock` and `stockQuantity`;
+  `create_upsell` / `create_downsell` take an optional `order`.
+
+### Fixed
+
+- **`update_checkout` sends only the checkout's identity and what changed.** The checkout API
+  keeps every key absent from the body as stored, so the tool no longer echoes the whole
+  document it read back (`paymentMethods`, the `checkout` object, `orderBumps`, `url`,
+  `fields`, `sellerName`, `currency`, `published`, `createBy`). Echoing it could overwrite
+  stored values the read does not carry (re-sent order bumps lost their per-bump original
+  price and button text); `paymentMethods`, `checkout` and `orderBumps` only travel when the
+  caller changes them.
+- `update_product` with only some fields was refused (400 "Você precisa fornecer um link
+  (url)…"): the API validates the body as a whole product. The stored product is now
+  re-sent with the edit on top.
+- `create_upsell` / `create_downsell` were refused on v2 accounts (422 "missing field
+  sortOrder") and, where accepted, stored an offer with no product to sell. They now write
+  `order` and `upsellProductIds` / `downsellProductIds` the way the dashboard does.
+- `update_funnel` with part of `design` or `settings` erased the rest of it. Both are now
+  merged into the stored funnel. Steps keep every field the editor stores (`loadingScreen`,
+  `allowBack`, `stickyButton`…), and the `level` and `social_proof` components are accepted.
+- `list_upsells` returned the API envelope instead of the list.
+- Store and funnel ids and coupon codes are URL-encoded; store read limits match the API.
+
 ## 0.3.0
 
 ### Breaking

package/README.md

@@ -1,6 +1,6 @@
 # GG Checkout MCP Server
 
-> Complete Model Context Protocol server for managing the GG Checkout platform via AI agents — 142 tools across 18 domains.
+> Complete Model Context Protocol server for managing the GG Checkout platform via AI agents — 189 tools across 19 domains.
 
 ## Overview
 
@@ -77,11 +77,22 @@ export GGCHECKOUT_API_KEY="ggck_live_your_key_here"
 export GGCHECKOUT_API_URL="https://your-staging.example.com"
 ```
 
+### Upload folder
+
+`upload_members_area_file` reads files from the machine running this server, and only from the
+folder named here. Without it the tool refuses every upload: what an agent reads (a page, a PDF) can
+carry instructions, so the server never reads an arbitrary path. A file that is itself a symbolic
+link is refused, and a path that leads outside the folder through a link is too.
+
+```bash
+export GGCHECKOUT_UPLOAD_ROOT="/home/me/course-import"
+```
+
 ---
 
-## Available Tools (142)
+## Available Tools (189)
 
-### Products (16 tools)
+### Products (18 tools)
 
 #### `list_products`
 
@@ -114,23 +125,43 @@ Create a new product/delivery.
 
 #### `update_product`
 
-Update an existing product. Only provide fields you want to change.
+Update an existing product. Only provide fields you want to change; everything else is kept.
 
 **Parameters:** `productId` + any fields from create_product (all optional)
 
+On accounts whose product read does not carry the file or the stock lines, an edit of a product
+that delivers only one of those is refused with an explanation: the API checks the request body
+for a deliverable, and those two cannot be read back to be sent along. Pass `url` with the
+change, or make it in the dashboard.
+
 **Example prompt:** "Update product abc123 price to R$79.90"
 
 #### `delete_product`
 
 **Example prompt:** "Delete product abc123"
 
-#### `upload_deliverable`
+#### `upload_deliverable` / `attach_deliverable` / `delete_deliverable`
+
+Attaching a file takes two tool calls and one upload you perform yourself — the bytes never pass
+through this server:
 
-Upload a deliverable file to a product.
+1. `upload_deliverable` (`productId`, `fileName`, `fileType`, `fileSize`) returns
+   `{ uploadUrl, filePath }`.
+2. `PUT` the raw bytes to `uploadUrl` with **only** `Content-Type: <fileType>` set. Do not send
+   an `Authorization` header — the signature is already in the URL and an extra header breaks it.
+   The URL is valid for one hour; the file may be up to 250MB.
+3. `attach_deliverable` (`productId`, `filePath`, `fileName`, `fileType`, `fileSize`) confirms the
+   upload landed and links it to the product.
 
-**Parameters:** `productId`, `fileUrl`, `fileName`, `fileType` (optional)
+`attach_deliverable` keeps any link (`url`) the product already has; when both exist, the file
+is what the buyer receives.
 
-**Example prompt:** "Upload the ebook at https://files.example.com/ebook.pdf to product abc123"
+`delete_deliverable` unlinks the file; pass `filePath` to delete the stored bytes as well. It is
+refused when the file is the product's only deliverable, since the API will not save a product
+with nothing to deliver: give it a `url` first. If the unlink works and the byte deletion does
+not, the answer carries `fileDeleteError` and the product stays unlinked.
+
+**Example prompt:** "Attach ebook.pdf (2MB, application/pdf) to product abc123"
 
 #### `list_upsells` / `create_upsell` / `delete_upsell` / `reorder_upsells`
 
@@ -147,6 +178,27 @@ Manage downsells for a product.
 
 **Example prompt:** "Add a downsell to product abc123 with a 50% discount headline"
 
+#### `get_offer_snippets` / `set_offer_product_page` (offers on the seller's page)
+
+The post-purchase funnel is one ordered sequence of products, and each product opens either on the
+GG offer page or on the seller's own page ("Minha página"). Both can be mixed in the same funnel: the
+funnel order decides where the buyer goes after accepting or declining, and each product opens on its
+own kind of page.
+
+- `set_offer_product_page` puts ONE product of an upsell or downsell on the seller's page (the page
+  where its buttons are pasted, the two texts and the button color), or back on the GG page with
+  `page: null` (the stored page is kept, so moving it back loses nothing).
+- `get_offer_snippets` is read only: every product of the offer in funnel order, and for each one on
+  the seller's page the HTML to paste there (the same as "Copiar HTML" in the dashboard) and the page
+  it goes on. An agent with access to the seller's landing page can paste each snippet where the
+  buttons should appear, keeping the `<script>` tag.
+
+Each snippet works only for its own product, when the funnel order reaches it. Pages must be https;
+plain http only works for localhost against a development server.
+
+**Example prompt:** "Put the second product of upsell u1 of product abc123 on https://seller.com/oferta
+with a green button saying 'Quero!', then give me the HTML to paste on that page"
+
 #### `manage_tags`
 
 Set tags on a product. Tags have a name and a hex color.
@@ -191,10 +243,9 @@ instead of silently vanishing from the page.
 
 #### `update_checkout`
 
-Auto-merges with current data — only provide fields you want to change. The API
-resets any field missing from the body rather than merging, so the whole document
-is re-sent on your behalf; edits made outside the MCP between the read and the
-write are the one thing this cannot preserve.
+Only provide the fields you want to change. The API keeps every field missing from
+the body as stored, so the tool sends the checkout's identity (title, owner, product,
+price) plus your changes and nothing else from the stored document.
 
 **Example prompt:** "Update checkout abc123 price to R$79.90 and unpublish it"
 
@@ -244,11 +295,30 @@ Manage physical order fulfillment.
 
 **Example prompts:**
 - "Show me all my webhooks"
-- "Create a webhook for payment.paid events at https://myapp.com/webhook"
-- "Update webhook abc123 to also listen for payment.refunded"
+- "Create a webhook for pix.paid events at https://myapp.com/webhook"
+- "Update webhook abc123 to also listen for card.paid"
 - "Delete webhook abc123"
-- "Send a test payment.paid event to webhook abc123"
-- "Test my webhook abc123 with a refunded event overriding the payment ID to pay_xyz"
+- "Send a test pix.paid event to webhook abc123"
+- "Test my webhook abc123 with an expired event overriding the payment ID to pay_xyz"
+
+#### Event names
+
+The API stores the event names you register **without checking them**, and delivery matches
+them exactly — so a name outside this list is accepted, saved, and never fires, with no error
+anywhere. These are the names that exist:
+
+| Family | Events |
+|---|---|
+| PIX | `pix.paid`, `pix.generated`, `pix.expired`, `pix.failed` |
+| Card | `card.paid`, `card.generated`, `card.expired`, `card.failed`, `card.pending` |
+| Subscription | `subscription.canceled`, `subscription.past_due`, `subscription.renewed` |
+| Quiz funnel | `quiz.completed`, `quiz.lead_captured` |
+| Cart | `checkout.abandoned` |
+
+There is **no refund or chargeback event**: nothing dispatches one. `pix.failed` and
+`card.pending` can be registered but have no emitter today. Names of the form
+`payment.*` are the platform's internal vocabulary between services, not seller webhooks —
+registering one gets you silence.
 
 #### Webhook Event Payloads
 
@@ -258,35 +328,35 @@ All events share the same top-level shape. Key fields:
 |---|---|---|
 | `event` | string | Event type (see below) |
 | `payment.id` | string | Payment identifier |
-| `payment.status` | string | `pending`, `paid`, `refunded`, `expired`, `chargeback` |
-| `payment.method` | string | `pix`, `pix.paid`, `card`, `card.paid` |
+| `payment.status` | string | `pending`, `paid`, `expired` |
+| `payment.method` | string | `pix`, `credit_card` |
 | `payment.amount` | number | Amount in **cents** (e.g. `9900` = R$99,00) |
 | `payment.customer.name` | string | Buyer name |
 | `payment.customer.email` | string | Buyer email |
 | `payment.customer.document` | string | CPF |
 | `payment.customer.phone` | string | Phone (E.164, e.g. `5511999999999`) |
 | `payment.createdAt` | string | ISO 8601 |
-| `payment.paidAt` | string \| undefined | Present on `payment.paid`, `payment.refunded`, `payment.chargeback` |
-| `payment.refundedAt` | string \| undefined | Present on `payment.refunded` |
-| `payment.expiredAt` | string \| undefined | Present on `payment.expired` |
+| `payment.paidAt` | string \| undefined | Present on `pix.paid` and `card.paid` |
+| `payment.expiredAt` | string \| undefined | Present on `pix.expired` and `card.expired` |
 | `product.id` | string | Product identifier |
 | `product.title` | string | Product name |
 
-**Supported events:**
+**What `test_webhook` sends.** These bodies are built by the MCP server and posted straight to
+your endpoint — the platform is not involved — so they are a plausible payment-shaped payload to
+exercise your handler with, not a byte-for-byte copy of a live delivery:
 
 ```json
-{ "event": "payment.created",    "payment": { "status": "pending",    "method": "pix" }, ... }
-{ "event": "payment.paid",       "payment": { "status": "paid",       "method": "pix.paid", "paidAt": "..." }, ... }
-{ "event": "payment.refunded",   "payment": { "status": "refunded",   "method": "pix.paid", "paidAt": "...", "refundedAt": "..." }, ... }
-{ "event": "payment.expired",    "payment": { "status": "expired",    "method": "pix", "expiredAt": "..." }, ... }
-{ "event": "payment.chargeback", "payment": { "status": "chargeback", "method": "card.paid", "paidAt": "..." }, ... }
+{ "event": "pix.paid",     "payment": { "status": "paid",    "method": "pix",         "paidAt": "..." }, ... }
+{ "event": "card.paid",    "payment": { "status": "paid",    "method": "credit_card", "paidAt": "..." }, ... }
+{ "event": "pix.expired",  "payment": { "status": "expired", "method": "pix",         "expiredAt": "..." }, ... }
+{ "event": "card.expired", "payment": { "status": "expired", "method": "credit_card", "expiredAt": "..." }, ... }
 ```
 
 **Signature verification** (when a `secret` is set):
 
 ```
 X-Webhook-Signature: sha256=<HMAC-SHA256(secret, raw_body)>
-X-GGCheckout-Event: payment.paid
+X-GGCheckout-Event: pix.paid
 ```
 
 ```ts
@@ -297,32 +367,64 @@ const isValid = sig === incomingHeader.replace('sha256=', '');
 
 ---
 
-### Store (9 tools)
+### Store (28 tools)
+
+`list_stores` returns your stores' ids; every other store tool takes one.
+
+**Manage the store:** `create_store`, `get_store`, `update_store`, `delete_store`;
+categories with `list_store_categories`, `create_store_category`, `update_store_category`,
+`delete_store_category`; review moderation with `list_store_reviews`, `create_store_review`,
+`update_store_review`, `delete_store_review`. `update_store` merges objects into the stored
+config and replaces lists (`productOrder`, gateways, a category's `productIds`). Creating or
+publishing a store requires a seller with verified email and phone.
+
+**Store builder:** `get_store_layout`, `update_store_layout`, `publish_store_layout`,
+`list_store_layout_history`, `restore_store_layout_version`, `get_store_theme`.
+`update_store_layout` saves a draft and merges `theme`, `config` and `pageSettings` into the
+stored ones; `blocks` replaces the whole list. Nothing is public until you publish.
+
+**Catalog reads** (`get_store_public`, `list_store_products`, `get_store_product`,
+`list_categories`, `list_feedbacks`) read the public storefront: they only see published
+stores, list approved reviews only, and may be cached for up to 7 days.
+`get_store_order` only returns pending orders with an API key.
+
+Store integrations, store upsells/downsells, video, sales notifications and custom fields
+are dashboard-only.
 
 **Example prompts:**
-- "Show me my store configuration"
+- "Create a store called 'Loja Teste', turn on PIX with my AmploPay gateway and publish it"
+- "Create a 'Cursos' category with products abc and def"
+- "Approve all pending reviews of my store"
+- "List my stores"
+- "Change the primary color of my store to #8b5cf6 and publish it"
+- "Undo the last store publish"
 - "List all products in my store"
-- "Get product details for product abc123 in store xyz"
-- "Show me the categories in my store"
 - "List customer reviews for my store with rating stats"
 - "Validate coupon code SAVE20 for an order of R$100"
 
 ---
 
-### Funnels / Quiz (9 tools)
+### Funnels / Quiz (10 tools)
+
+A quiz is a funnel: `question` components with options and scores, `result` components,
+`scoring.ranges` and conditional `flow.edges`. `update_funnel` merges `design` and `settings`
+into the stored ones; `steps`, `flow` and `scoring` replace the stored value, so read the
+funnel first and send the full array back. Pixels and webhooks are linked by id
+(`settings.pixelTokenIds` from `list_tokens`, `settings.webhookIds` from `list_webhooks`).
+`list_funnel_checkouts` gives the checkouts and gateways a `pix` component can use.
 
 **Example prompts:**
 - "List all my funnels"
-- "Show me the details of funnel abc123"
-- "Create a new funnel called 'Lead Capture'"
+- "Create a quiz with 3 questions that scores leads into beginner and advanced"
+- "Change the primary color of funnel abc123 to red"
+- "Send the leads of funnel abc123 to my Zapier webhook"
 - "Duplicate funnel abc123"
 - "Show me the leads from funnel abc123 that completed all steps"
-- "What's the conversion rate for funnel abc123?"
 - "Show me the drop-off analytics for each step in funnel abc123"
 
 ---
 
-### Members Area (21 tools)
+### Members Area (32 tools)
 
 **Example prompts:**
 - "List all my members areas"
@@ -335,6 +437,23 @@ const isValid = sig === incomingHeader.replace('sha256=', '');
 - "Import these 50 students to members area xyz"
 - "Block student abc123"
 
+**Files the seller sends.** `upload_members_area_file` uploads a file that is already on the machine
+running this server (an absolute path inside `GGCHECKOUT_UPLOAD_ROOT`, see "Upload folder") and
+returns the URL to pass on:
+
+| `kind` | Accepts | Use the `url` in |
+|---|---|---|
+| `image` | jpg, png, webp, gif, avif | `update_members_area` branding (logo, banner), module `imageUrl`, section and lesson `thumbnailUrl` |
+| `video` | mp4, webm, mov, avi, mpeg — up to 500 MB | `create_lesson` type `video`: `videoUrl` and `content: { videoUrl, videoSourceType: "upload" }` |
+| `file` | pdf, doc(x), xls(x), zip, rar, 7z, mp3, ogg, wav, images, videos — up to 100 MB; needs `areaId` | `create_pdf_lessons`, `create_lesson` `content.fileUrl`, or `add_lesson_attachment` |
+
+Nothing is downloaded from another platform: videos and PDFs come from the seller. Modules and
+sections take `dripSettings` (release N days after purchase, enrollment or first access); lessons
+take a cover and a position. `update_module` / `update_section` / `update_lesson` change only the
+fields sent, and `delete_module` / `delete_section` / `delete_lesson` remove the item with everything
+under it — irreversible, so they take `confirm: true`. These six need the API release with the
+`PATCH`/`DELETE` structure routes; an older deployment answers that it has no such route yet.
+
 ---
 
 ### Discounts / Coupons (6 tools)
@@ -348,7 +467,7 @@ const isValid = sig === incomingHeader.replace('sha256=', '');
 
 ---
 
-### WhatsApp (15 tools)
+### WhatsApp (13 tools)
 
 **Example prompts:**
 - "List my WhatsApp sessions"
@@ -363,7 +482,7 @@ const isValid = sig === incomingHeader.replace('sha256=', '');
 
 ---
 
-### Billing (10 tools)
+### Billing (11 tools)
 
 **Example prompts:**
 - "What's my current billing balance?"
@@ -386,14 +505,16 @@ const isValid = sig === incomingHeader.replace('sha256=', '');
 
 ---
 
-### Gateway Tokens (3 tools)
+### Gateway Tokens (4 tools)
 
 **Example prompts:**
 - "List my payment gateway tokens"
-- "Add a Stripe token"
+- "Add a PushinPay token"
 - "Remove token abc123"
 
-Supports 26+ gateways: pushinpay, mercadopago, stripe, efibank, amplopay, infinitepay, abacatepay, and more.
+`insert_token` creates only the four types the API accepts: `pushinpay`, `utmify`,
+`emailprovider` and `mercadopago`. The platform processes payments through 25+ gateways, but the
+others are connected from the dashboard, not through this API — asking for one here is refused.
 
 ---
 
@@ -427,13 +548,16 @@ Supports 26+ gateways: pushinpay, mercadopago, stripe, efibank, amplopay, infini
 
 ---
 
-### Rewards / Goals (3 tools)
+### Rewards / Goals (2 tools)
 
 **Example prompts:**
 - "What's my progress on sales milestones?"
-- "Recalculate my reward progress"
 - "Redeem the 10K bracelet reward"
 
+`calculate_rewards` is the only reader: it returns the progress and the milestone list together,
+in reais (`currentRevenueCents` carries the same value in cents). There is no reward catalogue
+endpoint, and a cache miss is rate limited to 10 per hour.
+
 ---
 
 ### Profile / Auth (6 tools)
@@ -455,6 +579,20 @@ Supports 26+ gateways: pushinpay, mercadopago, stripe, efibank, amplopay, infini
 
 ---
 
+### Telegram (15 tools)
+
+Bots (`list_telegram_bots`, `get_telegram_bot`, `create_telegram_bot`, `update_telegram_bot`,
+`delete_telegram_bot`, `validate_telegram_token`, `get_telegram_bot_groups`), flows
+(`list_telegram_flows`, `get_telegram_flow`, `create_telegram_flow`, `update_telegram_flow`,
+`delete_telegram_flow`, `deploy_telegram_flow`), `list_telegram_leads` and `telegram_media_upload`.
+
+**Example prompts:**
+- "List my Telegram bots"
+- "Create a basic flow for bot abc123 and deploy it"
+- "Show the qualified leads of bot abc123"
+
+---
+
 ## Price Formats
 
 Prices are accepted in two formats:
@@ -540,7 +678,7 @@ for each item:
 ## Local Development
 
 ```bash
-git clone https://github.com/gui-drumond/ggcheckout-mcp.git
+git clone https://github.com/ggCheckout/ggcheckout-mcp.git
 cd ggcheckout-mcp
 npm install
 ```
@@ -550,6 +688,7 @@ npm install
 ```bash
 GGCHECKOUT_API_KEY=ggck_live_your_key_here
 GGCHECKOUT_API_URL=http://localhost:3000  # optional, defaults to https://ggcheckout.app
+GGCHECKOUT_UPLOAD_ROOT=/path/to/import    # needed by upload_members_area_file, the only folder it reads from
 ```
 
 ### Commands
@@ -610,9 +749,9 @@ Opens a browser UI to test any tool interactively.
 
 ## Support
 
-- 📧 Email: support@ggcheckout.com
+- 📧 Email: suporte@ggcheckout.com
 - 📖 Docs: https://docs.ggcheckout.com
-- 🐛 Issues: https://github.com/gui-drumond/ggcheckout-mcp/issues
+- 🐛 Issues: https://github.com/ggCheckout/ggcheckout-mcp/issues
 
 ## License
 

package/dist/adapters/inbound/tools/billing.tools.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { BillingService } from '../../../core/services/billing.service.js';
+import { type BillingService } from '../../../core/services/billing.service.js';
 export declare function registerBillingTools(server: McpServer, service: BillingService): void;
 //# sourceMappingURL=billing.tools.d.ts.map

package/dist/adapters/inbound/tools/billing.tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"billing.tools.d.ts","sourceRoot":"","sources":["../../../../src/adapters/inbound/tools/billing.tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAC;AAGhF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,QAkE9E"}
+{"version":3,"file":"billing.tools.d.ts","sourceRoot":"","sources":["../../../../src/adapters/inbound/tools/billing.tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2CAA2C,CAAC;AAGnD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,QAiG9E"}