@ar-agents/mercadopago 0.3.0 → 0.4.0

package/dist/index.js

@@ -712,6 +712,188 @@ var MercadoPagoClient = class {
       `/instore/orders/qr/seller/collectors/${encodeURIComponent(userId)}/pos/${encodeURIComponent(externalPosId)}/qrs`
     );
   }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Subscription Plans (preapproval_plan — reusable plans, v0.4)
+  // ───────────────────────────────────────────────────────────────────────────
+  /**
+   * Create a reusable subscription plan. Customers later subscribe to it via
+   * `subscribeToPlan` (which creates a preapproval pointing at the plan).
+   *
+   * Use this when you have fixed tiers (Básico/Pro/Enterprise). For custom
+   * per-customer amounts, skip plans and use `createPreapproval` directly.
+   */
+  async createSubscriptionPlan(params) {
+    const body = {
+      reason: params.reason,
+      back_url: params.backUrl,
+      auto_recurring: {
+        frequency: params.frequency,
+        frequency_type: params.frequencyType,
+        transaction_amount: params.amount,
+        currency_id: params.currency,
+        ...params.freeTrialFrequency !== void 0 && params.freeTrialFrequencyType !== void 0 ? {
+          free_trial: {
+            frequency: params.freeTrialFrequency,
+            frequency_type: params.freeTrialFrequencyType
+          }
+        } : {}
+      }
+    };
+    if (params.externalReference) body.external_reference = params.externalReference;
+    return this.request("POST", "/preapproval_plan", body);
+  }
+  async getSubscriptionPlan(id) {
+    return this.request("GET", `/preapproval_plan/${id}`);
+  }
+  async listSubscriptionPlans(params = {}) {
+    const query = {
+      limit: params.limit ?? 30,
+      offset: params.offset ?? 0
+    };
+    if (params.status) query["status"] = params.status;
+    return this.request("GET", "/preapproval_plan/search", void 0, { query });
+  }
+  async updateSubscriptionPlan(id, patch) {
+    const body = {};
+    if (patch.reason !== void 0) body.reason = patch.reason;
+    if (patch.status !== void 0) body.status = patch.status;
+    if (patch.backUrl !== void 0) body.back_url = patch.backUrl;
+    if (patch.amount !== void 0) {
+      body.auto_recurring = { transaction_amount: patch.amount };
+    }
+    return this.request("PUT", `/preapproval_plan/${id}`, body);
+  }
+  /**
+   * Subscribe a customer to an existing plan. Returns a Preapproval with
+   * `init_point` URL where the buyer completes the first payment.
+   */
+  async subscribeToPlan(params) {
+    const body = {
+      preapproval_plan_id: params.planId,
+      payer_email: params.payerEmail
+    };
+    if (params.cardTokenId) body.card_token_id = params.cardTokenId;
+    if (params.externalReference) body.external_reference = params.externalReference;
+    return this.request("POST", "/preapproval", body, {
+      classifyContext: { payerEmail: params.payerEmail }
+    });
+  }
+  /**
+   * List the auto-charge attempts (authorized_payments) under a preapproval.
+   * Useful for "show me the cobros of the last 6 months for this client".
+   */
+  async listSubscriptionPayments(preapprovalId, params = {}) {
+    const query = {
+      preapproval_id: preapprovalId,
+      limit: params.limit ?? 30,
+      offset: params.offset ?? 0
+    };
+    return this.request(
+      "GET",
+      `/authorized_payments/search`,
+      void 0,
+      { query, classifyContext: { preapprovalId } }
+    );
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Stores + POS (for QR payments self-serve setup, v0.4)
+  // ───────────────────────────────────────────────────────────────────────────
+  /** Create a store for the seller. POSes (for QR) live under stores. */
+  async createStore(userId, params) {
+    const body = {
+      name: params.name,
+      external_id: params.externalId
+    };
+    if (params.location) {
+      body.location = {
+        ...params.location.addressLine ? { address_line: params.location.addressLine } : {},
+        ...params.location.cityName ? { city_name: params.location.cityName } : {},
+        ...params.location.stateName ? { state_name: params.location.stateName } : {},
+        ...params.location.countryId ? { country_id: params.location.countryId } : {},
+        ...params.location.latitude !== void 0 ? { latitude: params.location.latitude } : {},
+        ...params.location.longitude !== void 0 ? { longitude: params.location.longitude } : {}
+      };
+    }
+    return this.request("POST", `/users/${encodeURIComponent(userId)}/stores`, body);
+  }
+  async listStores(userId, params = {}) {
+    const query = {
+      limit: params.limit ?? 50,
+      offset: params.offset ?? 0
+    };
+    return this.request("GET", `/users/${encodeURIComponent(userId)}/stores/search`, void 0, { query });
+  }
+  /** Create a POS under a store. The POS's `external_id` is what `createQrPayment` uses. */
+  async createPos(params) {
+    const body = {
+      name: params.name,
+      external_id: params.externalId,
+      store_id: params.storeId,
+      category: params.category ?? 621102
+      // "Other Food and Beverage Services" — generic default
+    };
+    if (params.fixedAmount !== void 0) body.fixed_amount = params.fixedAmount;
+    return this.request("POST", "/pos", body);
+  }
+  async listPos(params = {}) {
+    const query = {
+      limit: params.limit ?? 50,
+      offset: params.offset ?? 0
+    };
+    if (params.storeId !== void 0) query["store_id"] = String(params.storeId);
+    return this.request("GET", "/pos", void 0, { query });
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Disputes (read-only, v0.4)
+  // ───────────────────────────────────────────────────────────────────────────
+  async listPaymentDisputes(paymentId) {
+    return this.request("GET", `/v1/payments/${paymentId}/disputes`, void 0, {
+      classifyContext: { paymentId }
+    });
+  }
+  async getDispute(paymentId, disputeId) {
+    return this.request(
+      "GET",
+      `/v1/payments/${paymentId}/disputes/${disputeId}`,
+      void 0,
+      { classifyContext: { paymentId } }
+    );
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Identification Types + Issuers (lookup helpers, v0.4)
+  // ───────────────────────────────────────────────────────────────────────────
+  /** List valid identification types for the seller's site. AR returns DNI/CI/LE/LC/Otro/Pasaporte/CUIT/CUIL. */
+  async listIdentificationTypes() {
+    return this.request("GET", "/v1/identification_types");
+  }
+  /** List card issuers for a payment method. Useful with `bin` for installments. */
+  async listIssuers(params) {
+    const query = {
+      payment_method_id: params.paymentMethodId
+    };
+    if (params.bin) query["bin"] = params.bin;
+    return this.request("GET", "/v1/payment_methods/card_issuers", void 0, { query });
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Webhooks management (v0.4)
+  // ───────────────────────────────────────────────────────────────────────────
+  /** List configured webhook subscriptions. */
+  async listWebhooks() {
+    return this.request("GET", "/v1/webhooks");
+  }
+  /** Create a webhook subscription for a topic. */
+  async createWebhook(params) {
+    return this.request("POST", "/v1/webhooks", {
+      url: params.url,
+      topic: params.topic
+    });
+  }
+  async updateWebhook(id, patch) {
+    return this.request("PUT", `/v1/webhooks/${id}`, patch);
+  }
+  async deleteWebhook(id) {
+    await this.request("DELETE", `/v1/webhooks/${id}`);
+  }
 };
 function deterministicIdempotencyKey(...parts) {
   const payload = parts.filter((p) => p !== void 0 && p !== null).map(String).join("|");
@@ -749,8 +931,30 @@ var DEFAULT_DESCRIPTIONS = {
   // ── Saved-card charging (v0.3) ───────────────────────────────────────────
   charge_saved_card: "Charge a previously-saved card for a returning customer. Requires customer_id + card_id (from list_customer_cards) AND a fresh CVV the user provides this session. AR Mercado Pago does NOT support CVV-less charges via the public API \u2014 every charge needs CVV. Idempotent on (card_id, amount, external_reference): retries dedupe automatically. Returns the resulting Payment.",
   // ── QR in-store (v0.3) ───────────────────────────────────────────────────
-  create_qr_payment: "Generate a dynamic in-store QR for a buyer to scan with any AR wallet (Modo, BNA+, Cuenta DNI, Naranja X, Mercado Pago, etc. \u2014 interop is mandated by Transferencias 3.0). Requires a pre-configured POS external_id (one-time setup in MP dashboard). Returns the qr_data string + a base64 PNG data URL ready to display. The QR expires in `expires_in_seconds` (default 600). MP fires `point_integration_wh` then `payment` webhooks when scanned.",
-  cancel_qr_payment: "Cancel a pending QR order on a POS. Necessary if the buyer never scans \u2014 otherwise the next create_qr_payment on the same POS returns 409."
+  create_qr_payment: "Generate a dynamic in-store QR for a buyer to scan with any AR wallet (Modo, BNA+, Cuenta DNI, Naranja X, Mercado Pago, etc. \u2014 interop is mandated by Transferencias 3.0). Requires a pre-configured POS external_id (use create_pos to set one up first if needed). Returns the qr_data string + a base64 PNG data URL ready to display. The QR expires in `expires_in_seconds` (default 600). MP fires `point_integration_wh` then `payment` webhooks when scanned.",
+  cancel_qr_payment: "Cancel a pending QR order on a POS. Necessary if the buyer never scans \u2014 otherwise the next create_qr_payment on the same POS returns 409.",
+  // ── Subscription Plans (v0.4) ────────────────────────────────────────────
+  create_subscription_plan: "Create a REUSABLE subscription plan (preapproval_plan). Different from create_subscription: a plan defines price + frequency once, then customers subscribe to it via subscribe_to_plan. Use plans for SaaS-style billing (B\xE1sico/Pro/Enterprise tiers). For per-customer custom amounts, use create_subscription directly.",
+  list_subscription_plans: "List all subscription plans defined for this MP account. Useful before create_subscription_plan to check if one already exists, or for surfacing options to a customer.",
+  update_subscription_plan: "Update a subscription plan's reason / amount / status / back_url. Existing customer subscriptions to the plan are NOT automatically updated \u2014 only NEW subscribers get the new pricing.",
+  subscribe_to_plan: "Subscribe a customer to an existing reusable plan. Returns a Preapproval with init_point URL where the customer completes first payment. Cleaner than create_subscription when you have fixed tiers.",
+  list_subscription_payments: "List the auto-charge attempts (authorized_payments) under a subscription. Useful for 'show me the cobros del \xFAltimo mes for this client' or to debug a failing recurring charge.",
+  // ── Stores + POS (v0.4) ──────────────────────────────────────────────────
+  create_store: "Create a store under the seller's MP account. Stores are the parent entity for POSes (which generate QR payments). Required ONE-TIME setup before create_pos. Pass a unique external_id and a display name.",
+  list_stores: "List all stores configured for this MP account. Use this to find an existing store_id before create_pos, or to surface store options to the agent.",
+  create_pos: "Create a POS (Point of Sale) under a store. The POS's external_id is what create_qr_payment uses. Each physical checkout / counter / agent typically has its own POS. Categories are MP-defined (default 621102 = Other Food and Beverage Services).",
+  list_pos: "List all POSes for the seller (or filtered by store_id). Use to find an existing POS before create_qr_payment, or to surface options.",
+  // ── Disputes (v0.4 — read-only) ──────────────────────────────────────────
+  list_payment_disputes: "List all disputes / chargebacks raised against a payment. Read-only \u2014 resolution is dashboard-only. Surface the dashboard URL `https://www.mercadopago.com.ar/disputes/{dispute_id}` to the user when they need to respond.",
+  get_dispute: "Get details of a specific dispute including reason, amount, resolution status. Read-only.",
+  // ── Lookup helpers (v0.4) ────────────────────────────────────────────────
+  list_identification_types: "List valid identification types for the seller's site. AR returns: DNI, CI, LE, LC, Otro, Pasaporte, CUIT, CUIL with their min/max length. Useful to validate an identification before passing to create_payment.",
+  list_issuers: "List card issuers (banks) that support a payment_method_id. Optionally filter by `bin` (first 6 digits of the card) for accurate issuer detection. Useful with calculate_installments \u2014 issuer-specific promos (e.g., Naranja Galicia 6 cuotas sin inter\xE9s) only appear when the issuer is identified.",
+  // ── Webhooks management (v0.4) ───────────────────────────────────────────
+  list_webhooks: "List all webhook subscriptions configured for this MP application. Use to see what topics + URLs are wired before adding new ones.",
+  create_webhook: "Subscribe a webhook URL to a MP topic (payment, subscription_authorized_payment, subscription_preapproval, merchant_order, point_integration_wh). MP will POST to this URL when events of that topic fire.",
+  update_webhook: "Update a webhook's URL or topic. Useful when you change deployment URLs without resubscribing from scratch.",
+  delete_webhook: "Delete a webhook subscription. MP stops POSTing to it immediately."
 };
 function mercadoPagoTools(client, options) {
   const desc = (name) => options.descriptions?.[name] ?? DEFAULT_DESCRIPTIONS[name];
@@ -1360,6 +1564,390 @@ function mercadoPagoTools(client, options) {
         await client.cancelQrPayment(String(me.id), external_pos_id);
         return { external_pos_id, cancelled: true };
       }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Subscription Plans (v0.4)
+    // ─────────────────────────────────────────────────────────────────────────
+    create_subscription_plan: tool({
+      description: desc("create_subscription_plan"),
+      inputSchema: z.object({
+        reason: z.string().min(3).max(120).describe("Plan name shown at checkout"),
+        amount_ars: z.number().positive(),
+        frequency_months: z.number().int().min(1).max(12),
+        back_url: z.string().url().describe("HTTPS URL where MP redirects after first payment"),
+        external_reference: z.string().optional(),
+        free_trial_days: z.number().int().min(1).max(60).optional().describe("Free trial period in days before first charge")
+      }),
+      execute: async (input) => {
+        const plan = await client.createSubscriptionPlan({
+          reason: input.reason,
+          amount: input.amount_ars,
+          currency: "ARS",
+          frequency: input.frequency_months,
+          frequencyType: "months",
+          backUrl: input.back_url,
+          ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
+          ...input.free_trial_days !== void 0 ? { freeTrialFrequency: input.free_trial_days, freeTrialFrequencyType: "days" } : {}
+        });
+        return {
+          plan_id: plan.id,
+          status: plan.status,
+          reason: plan.reason,
+          amount: plan.auto_recurring.transaction_amount,
+          currency: plan.auto_recurring.currency_id,
+          frequency: `${plan.auto_recurring.frequency} ${plan.auto_recurring.frequency_type}`,
+          external_reference: plan.external_reference,
+          next_step: "Use subscribe_to_plan to enroll customers in this plan, or share its ID for them to subscribe via your frontend."
+        };
+      }
+    }),
+    list_subscription_plans: tool({
+      description: desc("list_subscription_plans"),
+      inputSchema: z.object({
+        status: z.string().optional(),
+        limit: z.number().int().min(1).max(100).optional()
+      }),
+      execute: async (input) => {
+        const result = await client.listSubscriptionPlans({
+          ...input.status !== void 0 ? { status: input.status } : {},
+          ...input.limit !== void 0 ? { limit: input.limit } : {}
+        });
+        return {
+          total: result.paging.total,
+          plans: result.results.map((p) => ({
+            plan_id: p.id,
+            reason: p.reason,
+            status: p.status,
+            amount: p.auto_recurring.transaction_amount,
+            currency: p.auto_recurring.currency_id,
+            frequency: `${p.auto_recurring.frequency} ${p.auto_recurring.frequency_type}`
+          }))
+        };
+      }
+    }),
+    update_subscription_plan: tool({
+      description: desc("update_subscription_plan"),
+      inputSchema: z.object({
+        plan_id: z.string(),
+        reason: z.string().optional(),
+        amount_ars: z.number().positive().optional(),
+        status: z.enum(["active", "cancelled"]).optional(),
+        back_url: z.string().url().optional()
+      }),
+      execute: async (input) => {
+        const updated = await client.updateSubscriptionPlan(input.plan_id, {
+          ...input.reason !== void 0 ? { reason: input.reason } : {},
+          ...input.amount_ars !== void 0 ? { amount: input.amount_ars } : {},
+          ...input.status !== void 0 ? { status: input.status } : {},
+          ...input.back_url !== void 0 ? { backUrl: input.back_url } : {}
+        });
+        return {
+          plan_id: updated.id,
+          status: updated.status,
+          reason: updated.reason,
+          amount: updated.auto_recurring.transaction_amount,
+          message: input.amount_ars !== void 0 ? "Updated. Existing subscribers keep their old amount; only NEW subscribers get the new pricing." : "Plan updated."
+        };
+      }
+    }),
+    subscribe_to_plan: tool({
+      description: desc("subscribe_to_plan"),
+      inputSchema: z.object({
+        plan_id: z.string(),
+        customer_email: z.string().email(),
+        external_reference: z.string().optional()
+      }),
+      execute: async (input) => {
+        const sub = await client.subscribeToPlan({
+          planId: input.plan_id,
+          payerEmail: input.customer_email,
+          ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {}
+        });
+        return {
+          subscription_id: sub.id,
+          status: sub.status,
+          payer_email: sub.payer_email,
+          init_point_url: sub.init_point,
+          next_step: "Send init_point_url to the customer for first payment with card+CVV."
+        };
+      }
+    }),
+    list_subscription_payments: tool({
+      description: desc("list_subscription_payments"),
+      inputSchema: z.object({
+        subscription_id: z.string(),
+        limit: z.number().int().min(1).max(100).optional()
+      }),
+      execute: async (input) => {
+        const result = await client.listSubscriptionPayments(input.subscription_id, {
+          ...input.limit !== void 0 ? { limit: input.limit } : {}
+        });
+        return {
+          subscription_id: input.subscription_id,
+          total: result.paging.total,
+          payments: result.results.map((p) => ({
+            authorized_payment_id: p.id,
+            payment_id: p.payment_id ?? null,
+            status: p.status,
+            amount: p.transaction_amount ?? null,
+            currency: p.currency_id ?? null,
+            debit_date: p.debit_date ?? null,
+            next_retry_date: p.next_retry_date ?? null,
+            retry_attempt: p.retry_attempt ?? 0,
+            reason: p.reason ?? null
+          }))
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Stores + POS (v0.4)
+    // ─────────────────────────────────────────────────────────────────────────
+    create_store: tool({
+      description: desc("create_store"),
+      inputSchema: z.object({
+        name: z.string().min(1).max(80),
+        external_id: z.string().min(1).max(64).describe("Unique within the seller's stores"),
+        address_line: z.string().optional(),
+        city_name: z.string().optional(),
+        state_name: z.string().optional()
+      }),
+      execute: async (input) => {
+        const me = await client.getMe();
+        const store = await client.createStore(String(me.id), {
+          name: input.name,
+          externalId: input.external_id,
+          ...input.address_line || input.city_name || input.state_name ? {
+            location: {
+              ...input.address_line ? { addressLine: input.address_line } : {},
+              ...input.city_name ? { cityName: input.city_name } : {},
+              ...input.state_name ? { stateName: input.state_name } : {},
+              countryId: "AR"
+            }
+          } : {}
+        });
+        return {
+          store_id: store.id,
+          name: store.name,
+          external_id: store.external_id,
+          next_step: "Use create_pos with this store_id to add a Point of Sale where create_qr_payment can issue QRs."
+        };
+      }
+    }),
+    list_stores: tool({
+      description: desc("list_stores"),
+      inputSchema: z.object({
+        limit: z.number().int().min(1).max(100).optional()
+      }),
+      execute: async (input) => {
+        const me = await client.getMe();
+        const result = await client.listStores(String(me.id), {
+          ...input.limit !== void 0 ? { limit: input.limit } : {}
+        });
+        return {
+          total: result.paging.total,
+          stores: result.results.map((s) => ({
+            store_id: s.id,
+            name: s.name ?? null,
+            external_id: s.external_id ?? null
+          }))
+        };
+      }
+    }),
+    create_pos: tool({
+      description: desc("create_pos"),
+      inputSchema: z.object({
+        name: z.string().min(1).max(80),
+        external_id: z.string().min(1).max(64).describe("Unique within the store. This is what create_qr_payment uses."),
+        store_id: z.string().describe("From create_store / list_stores"),
+        category: z.number().int().optional().describe("MP category code, default 621102 (other food/beverage)"),
+        fixed_amount: z.boolean().optional().describe("True for static QR with fixed amount; false (default) for dynamic per-order QR")
+      }),
+      execute: async (input) => {
+        const pos = await client.createPos({
+          name: input.name,
+          externalId: input.external_id,
+          storeId: input.store_id,
+          ...input.category !== void 0 ? { category: input.category } : {},
+          ...input.fixed_amount !== void 0 ? { fixedAmount: input.fixed_amount } : {}
+        });
+        return {
+          pos_id: pos.id,
+          external_id: pos.external_id,
+          store_id: pos.store_id,
+          name: pos.name,
+          next_step: "Use create_qr_payment with this external_id to start issuing dynamic QRs from this POS."
+        };
+      }
+    }),
+    list_pos: tool({
+      description: desc("list_pos"),
+      inputSchema: z.object({
+        store_id: z.string().optional(),
+        limit: z.number().int().min(1).max(100).optional()
+      }),
+      execute: async (input) => {
+        const result = await client.listPos({
+          ...input.store_id !== void 0 ? { storeId: input.store_id } : {},
+          ...input.limit !== void 0 ? { limit: input.limit } : {}
+        });
+        return {
+          total: result.paging.total,
+          pos: result.results.map((p) => ({
+            pos_id: p.id,
+            external_id: p.external_id ?? null,
+            store_id: p.store_id ?? null,
+            name: p.name ?? null
+          }))
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Disputes (v0.4 — read-only)
+    // ─────────────────────────────────────────────────────────────────────────
+    list_payment_disputes: tool({
+      description: desc("list_payment_disputes"),
+      inputSchema: z.object({ payment_id: z.string() }),
+      execute: async ({ payment_id }) => {
+        const disputes = await client.listPaymentDisputes(payment_id);
+        return {
+          payment_id,
+          count: disputes.length,
+          disputes: disputes.map((d) => ({
+            dispute_id: d.id,
+            status: d.status,
+            amount: d.amount ?? null,
+            reason: d.reason ?? null,
+            date_created: d.date_created ?? null,
+            dashboard_url: `https://www.mercadopago.com.ar/disputes/${d.id}`
+          }))
+        };
+      }
+    }),
+    get_dispute: tool({
+      description: desc("get_dispute"),
+      inputSchema: z.object({
+        payment_id: z.string(),
+        dispute_id: z.string()
+      }),
+      execute: async ({ payment_id, dispute_id }) => {
+        const d = await client.getDispute(payment_id, dispute_id);
+        return {
+          dispute_id: d.id,
+          status: d.status,
+          amount: d.amount ?? null,
+          reason: d.reason ?? null,
+          reason_description: d.reason_description ?? null,
+          resolution: d.resolution ?? null,
+          date_created: d.date_created ?? null,
+          dashboard_url: `https://www.mercadopago.com.ar/disputes/${d.id}`
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Lookup helpers (v0.4)
+    // ─────────────────────────────────────────────────────────────────────────
+    list_identification_types: tool({
+      description: desc("list_identification_types"),
+      inputSchema: z.object({}),
+      execute: async () => {
+        const types = await client.listIdentificationTypes();
+        return {
+          count: types.length,
+          types: types.map((t) => ({
+            id: t.id,
+            name: t.name,
+            type: t.type,
+            min_length: t.min_length ?? null,
+            max_length: t.max_length ?? null
+          }))
+        };
+      }
+    }),
+    list_issuers: tool({
+      description: desc("list_issuers"),
+      inputSchema: z.object({
+        payment_method_id: z.string().describe("E.g. 'visa', 'master', 'naranja'"),
+        bin: z.string().min(6).max(8).optional().describe("First 6-8 digits of card for precise issuer detection")
+      }),
+      execute: async (input) => {
+        const issuers = await client.listIssuers({
+          paymentMethodId: input.payment_method_id,
+          ...input.bin !== void 0 ? { bin: input.bin } : {}
+        });
+        return {
+          payment_method_id: input.payment_method_id,
+          count: issuers.length,
+          issuers: issuers.map((i) => ({
+            issuer_id: i.id,
+            name: i.name,
+            status: i.status ?? null
+          }))
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Webhooks management (v0.4)
+    // ─────────────────────────────────────────────────────────────────────────
+    list_webhooks: tool({
+      description: desc("list_webhooks"),
+      inputSchema: z.object({}),
+      execute: async () => {
+        const hooks = await client.listWebhooks();
+        return {
+          count: hooks.length,
+          webhooks: hooks.map((h) => ({
+            webhook_id: h.id,
+            url: h.url ?? null,
+            topic: h.topic ?? null,
+            status: h.status ?? null,
+            date_created: h.date_created ?? null
+          }))
+        };
+      }
+    }),
+    create_webhook: tool({
+      description: desc("create_webhook"),
+      inputSchema: z.object({
+        url: z.string().url(),
+        topic: z.string().describe("E.g. 'payment', 'subscription_authorized_payment', 'subscription_preapproval', 'merchant_order', 'point_integration_wh'")
+      }),
+      execute: async ({ url, topic }) => {
+        const hook = await client.createWebhook({ url, topic });
+        return {
+          webhook_id: hook.id,
+          url: hook.url ?? url,
+          topic: hook.topic ?? topic,
+          status: hook.status ?? null
+        };
+      }
+    }),
+    update_webhook: tool({
+      description: desc("update_webhook"),
+      inputSchema: z.object({
+        webhook_id: z.string(),
+        url: z.string().url().optional(),
+        topic: z.string().optional()
+      }),
+      execute: async (input) => {
+        const hook = await client.updateWebhook(input.webhook_id, {
+          ...input.url !== void 0 ? { url: input.url } : {},
+          ...input.topic !== void 0 ? { topic: input.topic } : {}
+        });
+        return {
+          webhook_id: hook.id,
+          url: hook.url ?? null,
+          topic: hook.topic ?? null,
+          status: hook.status ?? null
+        };
+      }
+    }),
+    delete_webhook: tool({
+      description: desc("delete_webhook"),
+      inputSchema: z.object({ webhook_id: z.string() }),
+      execute: async ({ webhook_id }) => {
+        await client.deleteWebhook(webhook_id);
+        return { webhook_id, deleted: true };
+      }
     })
   };
 }
@@ -1580,6 +2168,105 @@ z.object({
   user_type: z.string().nullable().optional(),
   status: z.object({ user_type: z.string().nullable().optional() }).passthrough().nullable().optional()
 }).passthrough();
+z.object({
+  id: z.string(),
+  status: z.string(),
+  reason: z.string(),
+  back_url: z.string().url().optional(),
+  external_reference: z.string().nullable().optional(),
+  date_created: z.string(),
+  last_modified: z.string(),
+  auto_recurring: AutoRecurringSchema
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  name: z.string().optional(),
+  external_id: z.string().optional(),
+  date_creation: z.string().optional(),
+  location: z.object({
+    address_line: z.string().optional(),
+    city_name: z.string().optional(),
+    state_name: z.string().optional(),
+    country_id: z.string().optional(),
+    latitude: z.number().optional(),
+    longitude: z.number().optional()
+  }).passthrough().optional()
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  name: z.string().optional(),
+  external_id: z.string().optional(),
+  store_id: z.union([z.string(), z.number()]).optional(),
+  category: z.number().int().optional(),
+  fixed_amount: z.boolean().optional(),
+  qr: z.object({
+    template_image: z.string().optional(),
+    image: z.string().optional()
+  }).passthrough().optional(),
+  date_creation: z.string().optional()
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  status: z.string(),
+  resource: z.string().optional(),
+  resource_id: z.union([z.string(), z.number()]).optional(),
+  amount: z.number().optional(),
+  date_created: z.string().optional(),
+  reason: z.string().optional(),
+  resolution: z.object({
+    reason: z.string().optional(),
+    result: z.string().optional(),
+    date: z.string().optional()
+  }).passthrough().optional(),
+  /** Documents the buyer / seller submitted as evidence. */
+  documents: z.array(z.unknown()).optional(),
+  /** Buyer's stated complaint. */
+  reason_description: z.string().optional()
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  preapproval_id: z.string().optional(),
+  status: z.string(),
+  payment_id: z.union([z.string(), z.number()]).nullable().optional(),
+  transaction_amount: z.number().optional(),
+  currency_id: z.string().optional(),
+  date_created: z.string().optional(),
+  debit_date: z.string().optional(),
+  next_retry_date: z.string().nullable().optional(),
+  retry_attempt: z.number().optional(),
+  reason: z.string().optional()
+}).passthrough();
+z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.string(),
+  min_length: z.number().optional(),
+  max_length: z.number().optional()
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  name: z.string(),
+  secure_thumbnail: z.string().nullable().optional(),
+  thumbnail: z.string().nullable().optional(),
+  processing_mode: z.string().optional(),
+  status: z.string().optional()
+}).passthrough();
+z.enum([
+  "payment",
+  "subscription_authorized_payment",
+  "subscription_preapproval",
+  "merchant_order",
+  "point_integration_wh",
+  "stop_delivery_op_wh"
+]);
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  url: z.string().url().optional(),
+  status: z.string().optional(),
+  topic: z.string().optional(),
+  date_created: z.string().optional(),
+  date_modified: z.string().optional()
+}).passthrough();
 
 // src/webhook.ts
 function parseWebhookEvent(body, searchParams) {