ggcheckout-mcp 0.2.4 → 0.4.0

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
 
@@ -36,6 +36,14 @@ npm install -g ggcheckout-mcp
 
 ### Claude Code
 
+> **Upgrading?** The snippet below is unpinned: `npx -y ggcheckout-mcp` picks up
+> **every** new version on the next start — minor releases included, not just
+> majors. 0.3.0 carries two breaking changes: `create_checkout` takes
+> `productId` instead of `id`, and checkout reads (`list_checkouts`,
+> `get_checkout`, `update_checkout`) return that pointer as `productId` instead
+> of `id`. Read [CHANGELOG.md](./CHANGELOG.md) first, and pin
+> `ggcheckout-mcp@0.2.4` if this is not the moment.
+
 ```json
 {
   "mcpServers": {
@@ -69,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`
 
@@ -106,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`
 
@@ -139,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.
@@ -157,17 +217,35 @@ Set tags on a product. Tags have a name and a hex color.
 
 **Example prompt:** "Get details of checkout abc123"
 
-> **Note:** Use the `uid` (Firestore document ID), not the custom `id` slug.
+> **Note:** A checkout has two identifiers, and every response carries both. Its
+> own is `uid` (Firestore document ID) — that is what `get_checkout`,
+> `update_checkout`, `delete_checkout` and `manage_checkout_tags` take. The other
+> is `productId`, a foreign key pointing at the product this checkout sells; the
+> API names that field `id`, and the server renames it on the way in and out.
 
 #### `create_checkout`
 
-**Required:** `title`, `id` (slug), `price`, `paymentMethods`, `checkout` (config)
+Creates an offer for a product that already exists.
+
+**Required:** `title`, `productId`, `price`, `paymentMethods`, `checkout` (config)
+
+`productId` must be the uid returned by `create_product` (or a `uid` from
+`list_products`) — not a slug. A checkout created against a product that doesn't
+exist is an orphan the dashboard cannot open, so this is validated before the
+checkout is created.
+
+`price` is in Reais (`99.90`) and is converted to the cents the API stores.
+`orderBumps` takes product uids; each one is resolved and snapshotted into the
+shape the checkout page reads, so a uid that does not exist fails the call
+instead of silently vanishing from the page.
 
 **Example prompt:** "Create a checkout page for my React Course priced at R$99.90"
 
 #### `update_checkout`
 
-Auto-merges with current data — only provide fields you want to change.
+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"
 
@@ -217,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
 
@@ -231,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
@@ -270,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"
@@ -308,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)
@@ -321,7 +467,7 @@ const isValid = sig === incomingHeader.replace('sha256=', '');
 
 ---
 
-### WhatsApp (15 tools)
+### WhatsApp (13 tools)
 
 **Example prompts:**
 - "List my WhatsApp sessions"
@@ -336,7 +482,7 @@ const isValid = sig === incomingHeader.replace('sha256=', '');
 
 ---
 
-### Billing (10 tools)
+### Billing (11 tools)
 
 **Example prompts:**
 - "What's my current billing balance?"
@@ -359,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.
 
 ---
 
@@ -400,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)
@@ -428,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:
@@ -513,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
 ```
@@ -523,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
@@ -561,7 +727,11 @@ Opens a browser UI to test any tool interactively.
 ### Error: 404 Not Found
 
 - The resource ID doesn't exist
-- For checkouts, use the `uid` (Firestore document ID), not the custom `id` slug
+- For checkouts, use the `uid` (Firestore document ID) returned by `list_checkouts`
+- Note that `create_checkout` takes a different identifier: `productId`, the uid
+  of the product being sold
+- `Product <id> not found` from `create_checkout` means the product is missing or
+  belongs to another seller — the API answers 403 for both, so they look alike
 
 ### Error: 429 Too Many Requests
 
@@ -579,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/__e2e__/setup.js

@@ -46,7 +46,7 @@ export const adapters = {
 export const services = {
     product: new ProductService(adapters.product),
     payment: new PaymentService(adapters.payment, authAdapter),
-    checkout: new CheckoutService(adapters.checkout, authAdapter),
+    checkout: new CheckoutService(adapters.checkout, authAdapter, adapters.product),
     webhook: new WebhookService(adapters.webhook, authAdapter),
     store: new StoreService(adapters.store),
     funnel: new FunnelService(adapters.funnel),

package/dist/__e2e__/setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/__e2e__/setup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/__e2e__/setup.ts"],"names":[],"mappings":"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"}

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"}

package/dist/adapters/inbound/tools/billing.tools.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { MAX_TOPUP_CENTS, MIN_TOPUP_CENTS, } from '../../../core/services/billing.service.js';
 import { createToolHandler } from '../tool-handler.js';
 export function registerBillingTools(server, service) {
     server.tool('get_billing_balance', 'Get current billing balance, credit, usage %, and next charge date', createToolHandler('get_billing_balance', async () => service.getBalance()));
@@ -32,18 +33,43 @@ export function registerBillingTools(server, service) {
         },
     }, createToolHandler('pay_invoice', async ({ invoiceId, method }) => service.payInvoice(invoiceId, method)));
     server.registerTool('list_credits', {
-        description: 'List billing credits',
+        description: 'The credit statement. Returns `credits` (legacy PIX credits, with `status`) and `ledger` '
+            + '({ entries, nextBefore }), which is the statement for an account on the new billing. One of '
+            + 'the two is empty depending on the account, and that is the true answer, not an error: read '
+            + 'whichever has rows. Ledger `amountCents` is signed (credit +, debit −) and `balanceAfterCents` '
+            + 'is the running balance. Page the ledger by passing `before` = the `nextBefore` you got. If one '
+            + 'side could not be read, its list is empty and `creditsError` / `ledgerError` says why.',
         inputSchema: {
-            status: z.enum(['pending', 'confirmed', 'used', 'expired']).optional().describe('Filter by credit status'),
-            limit: z.number().min(1).max(1000).optional().describe('Max credits to return (default: 20)'),
+            status: z.enum(['pending', 'confirmed', 'used', 'expired']).optional()
+                .describe('Filter the legacy credits by status (does not apply to the ledger)'),
+            limit: z.number().int().min(1).max(200).optional()
+                .describe('Max rows (legacy default 20, ledger default 50; 200 is the lowest cap of the two routes)'),
+            before: z.string().optional()
+                .describe('Ledger cursor: the `nextBefore` from the previous page (RFC3339)'),
         },
     }, createToolHandler('list_credits', async (args) => service.listCredits(args)));
     server.registerTool('add_credit', {
-        description: 'Add billing credit via PIX. Returns QR code for payment.',
+        description: 'Add billing credit via PIX. Returns { creditId, amountCents, pixCode, pixQrBase64, expiresAt, via }: '
+            + '`pixCode` is the copy-and-paste string and `pixQrBase64` the QR image (base64, no `data:` prefix). '
+            + 'Works on both billing generations — the right route is picked for the account, and `via` says '
+            + 'which one answered. The credit only exists once the PIX is actually paid. On a timeout, a 502 '
+            + 'or a 504 the PIX may have been opened anyway: check get_credit_topup (new billing) or the pending '
+            + 'entries of list_credits (legacy) before calling this again.',
         inputSchema: {
-            amountCents: z.number().min(0).describe('Credit amount in cents'),
+            amountCents: z.number()
+                .int('amountCents is a whole number of CENTS: R$ 10,00 is 1000')
+                .min(MIN_TOPUP_CENTS, `amountCents is at least ${MIN_TOPUP_CENTS} CENTS (R$ 3,25)`)
+                .max(MAX_TOPUP_CENTS, `amountCents is at most ${MAX_TOPUP_CENTS} CENTS (R$ 250,00)`)
+                .describe(`Credit amount in CENTS, ${MIN_TOPUP_CENTS} to ${MAX_TOPUP_CENTS} (R$ 3,25 to R$ 250,00). R$ 10,00 is 1000`),
+            idempotencyKey: z.string().min(1).max(128).optional()
+                .describe('A stable key that makes a retry reuse the same top-up instead of opening another. Only '
+                + 'the new billing reads it (without one it dedupes by amount within 2 minutes); the legacy '
+                + 'billing ignores it and reuses the PIX already opened for the same amount, for 30 minutes.'),
         },
-    }, createToolHandler('add_credit', async ({ amountCents }) => service.addCredit(amountCents)));
+    }, createToolHandler('add_credit', async ({ amountCents, idempotencyKey }) => service.addCredit(amountCents, idempotencyKey)));
+    server.tool('get_credit_topup', 'The current credit top-up on the new billing: { creditId, amountCents, status (pending, paid, '
+        + 'expired), pixCode, pixQrBase64, expiresAt }, or null when there is none. A pending top-up is not '
+        + 'in the list_credits ledger until it is paid, so this is where to find one opened by add_credit.', createToolHandler('get_credit_topup', async () => ({ topup: await service.getCreditTopup() })));
     server.tool('get_card_status', 'Get saved card status (validated, brand, last four, expiring soon)', createToolHandler('get_card_status', async () => service.getCardStatus()));
     server.tool('remove_card', 'Remove the saved billing card', createToolHandler('remove_card', async () => {
         await service.removeCard();

package/dist/adapters/inbound/tools/billing.tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"billing.tools.js","sourceRoot":"","sources":["../../../../src/adapters/inbound/tools/billing.tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"billing.tools.js","sourceRoot":"","sources":["../../../../src/adapters/inbound/tools/billing.tools.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"checkout.tools.d.ts","sourceRoot":"","sources":["../../../../src/adapters/inbound/tools/checkout.tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAoDlF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,QAoHhF"}
+{"version":3,"file":"checkout.tools.d.ts","sourceRoot":"","sources":["../../../../src/adapters/inbound/tools/checkout.tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAoDlF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,QA6HhF"}

package/dist/adapters/inbound/tools/checkout.tools.js

@@ -58,18 +58,20 @@ export function registerCheckoutTools(server, service) {
         return { checkout };
     }));
     server.registerTool('create_checkout', {
-        description: 'Create a new checkout page',
+        description: 'Create a new checkout page (an offer for an existing product)',
         inputSchema: {
             title: z.string().max(200).describe('Checkout page title'),
-            id: z.string().max(100).describe('Unique checkout ID (slug)'),
-            price: z.number().min(0).describe('Price in Brazilian Reais (e.g., 99.90)'),
+            productId: z.string().min(1).max(100).regex(/^[A-Za-z0-9_-]+$/, 'productId must be a product uid').describe('Uid of the product this checkout sells — the `productId` returned by create_product, '
+                + 'or a `uid` from list_products. NOT a slug and NOT a name you invent: an invented '
+                + 'value creates an orphan checkout the seller cannot open in the dashboard.'),
+            price: z.number().min(0).describe('Price in Brazilian Reais (e.g., 99.90) — converted to cents before it is sent'),
             paymentMethods: paymentMethodsSchema.describe('Payment methods configuration (credit_card, pix, bank_slip)'),
             checkout: z.record(z.string(), z.unknown()).describe('Checkout page styling/configuration'),
             url: z.string().url().optional().describe('Checkout URL (optional)'),
             bannerUrl: z.string().url().optional().describe('Banner image URL (optional)'),
             image: z.string().url().optional().describe('Product image URL (optional)'),
             sellerName: z.string().max(200).optional().describe('Seller name (optional)'),
-            orderBumps: z.array(z.string()).max(20).optional().describe('Order bump product IDs (optional)'),
+            orderBumps: z.array(z.string()).max(20).optional().describe('Uids of products offered as order bumps, resolved and snapshotted server-side (optional)'),
             fields: fieldsSchema.optional().describe('Custom form fields config (havePhone, haveName, haveCpf)'),
             socialCard: socialCardSchema.optional().describe('Social proof cards (optional)'),
             published: z.boolean().optional().describe('Published status (default: true)'),
@@ -85,14 +87,19 @@ export function registerCheckoutTools(server, service) {
         inputSchema: {
             checkoutId: z.string().describe('Checkout ID (uid)'),
             title: z.string().max(200).optional().describe('Checkout page title'),
-            price: z.number().min(0).optional().describe('Price in Brazilian Reais'),
+            price: z.number().min(0).optional().describe('Price in Brazilian Reais — converted to cents before it is sent'),
             paymentMethods: paymentMethodsSchema.optional().describe('Payment methods configuration'),
-            checkout: z.record(z.string(), z.unknown()).optional().describe('Checkout page styling/configuration'),
-            url: z.string().url().optional().describe('Checkout URL'),
+            checkout: z.record(z.string(), z.unknown()).optional()
+                .describe('Checkout page configuration, merged into the stored one (send only the keys to change). '
+                + 'Payment methods are changed through `paymentMethods`; the stored ones are never re-sent from here'),
+            url: z.string().url().optional()
+                .describe('Where the buyer goes after the post-purchase funnel (upsells and downsells), or right after the '
+                + "purchase when there is none. The offers on the seller's own page are set per product with "
+                + 'set_offer_product_page, not here'),
             bannerUrl: z.string().url().optional().describe('Banner image URL'),
             image: z.string().url().optional().describe('Product image URL'),
             sellerName: z.string().max(200).optional().describe('Seller name'),
-            orderBumps: z.array(z.string()).max(20).optional().describe('Order bump product IDs'),
+            orderBumps: z.array(z.string()).max(20).optional().describe('Uids of products offered as order bumps, resolved and snapshotted server-side'),
             fields: fieldsSchema.optional().describe('Custom form fields config'),
             socialCard: socialCardSchema.optional().describe('Social proof cards'),
             published: z.boolean().optional().describe('Published status'),