@ar-agents/mercadopago 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -960,6 +960,280 @@ var MercadoPagoClient = class {
   async cancelOrder(id) {
     return this.request("POST", `/v1/orders/${id}/cancel`);
   }
+  // ──────────────────────────────────────────────────────────────────────────
+  // v0.6 — Account Balance + Movements
+  //
+  // Inspect the seller's MP wallet — what's available to withdraw, what's
+  // in retention (pending release), and the movement log.
+  //
+  // For per-seller marketplace setups, instantiate the client AS THE SELLER
+  // (with their OAuth access_token) before calling these — `getAccountBalance`
+  // returns the balance of WHOEVER's accessToken is active.
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * Get the seller's current MP wallet balance (available + unavailable).
+   * - `available_balance`: spendable / withdrawable right now.
+   * - `unavailable_balance`: in retention (e.g., 14-21 days for new sellers).
+   * - `total_amount` = sum of both.
+   */
+  async getAccountBalance() {
+    return this.request("GET", "/users/me/mercadopago_account/balance");
+  }
+  /**
+   * List wallet movements (incoming payments, transfers, refunds, holdings).
+   * Defaults to most-recent-first, paginated. Filter by date range with
+   * `from`/`to` (ISO 8601).
+   */
+  async listAccountMovements(params = {}) {
+    const query = {};
+    if (params.from) query.begin_date = params.from;
+    if (params.to) query.end_date = params.to;
+    if (params.limit !== void 0) query.limit = params.limit;
+    if (params.offset !== void 0) query.offset = params.offset;
+    const result = await this.request("GET", "/users/me/mercadopago_account/movements/search", void 0, { query });
+    return {
+      movements: result.results ?? [],
+      paging: result.paging ?? { limit: params.limit ?? 25, offset: params.offset ?? 0, total: 0 }
+    };
+  }
+  // ──────────────────────────────────────────────────────────────────────────
+  // v0.6 — Settlements (release_money)
+  //
+  // When MP transfers funds from your MP wallet to your registered CBU.
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * List settlements (transfers from MP wallet to your bank account).
+   * Useful for monthly conciliation reports.
+   */
+  async listSettlements(params = {}) {
+    const query = {};
+    if (params.from) query.begin_date = params.from;
+    if (params.to) query.end_date = params.to;
+    if (params.status) query.status = params.status;
+    if (params.limit !== void 0) query.limit = params.limit;
+    if (params.offset !== void 0) query.offset = params.offset;
+    const result = await this.request("GET", "/v1/account/release_money/search", void 0, { query });
+    return {
+      settlements: result.results ?? [],
+      paging: result.paging ?? { limit: params.limit ?? 25, offset: params.offset ?? 0, total: 0 }
+    };
+  }
+  /**
+   * Get a single settlement by id. Returns the full Settlement object
+   * including bank_account info (CBU, bank name).
+   */
+  async getSettlement(id) {
+    return this.request("GET", `/v1/account/release_money/${id}`);
+  }
+  // ──────────────────────────────────────────────────────────────────────────
+  // v0.7 — Customer + Card extensions (close gaps)
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * Update a customer's profile (name, last name, address, etc.). MP merges
+   * the patch — fields you don't send remain unchanged.
+   */
+  async updateCustomer(id, patch) {
+    return this.request("PUT", `/v1/customers/${id}`, patch);
+  }
+  /**
+   * Add a saved card to a customer using a card token (one-time, get from
+   * MP's frontend Cardform). The card is then chargeable with charge_saved_card.
+   */
+  async createCustomerCard(customerId, cardToken) {
+    return this.request(
+      "POST",
+      `/v1/customers/${customerId}/cards`,
+      { token: cardToken }
+    );
+  }
+  // ──────────────────────────────────────────────────────────────────────────
+  // v0.7 — Subscription extensions
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * Update an existing subscription. Common patches:
+   * - `transaction_amount` to change the recurring amount
+   * - `card_token_id` to switch payment method (e.g., expired card)
+   * - `status: "cancelled" | "paused"` (alternative to dedicated cancel/pause endpoints)
+   * - `reason` to update the description shown to the buyer
+   */
+  async updatePreapproval(id, patch) {
+    return this.request("PUT", `/preapproval/${id}`, patch);
+  }
+  /**
+   * Search subscriptions across the seller's account. Common filters:
+   * `status` (pending/authorized/paused/cancelled), `payer_email`,
+   * `external_reference`. Paginated.
+   */
+  async searchPreapprovals(params = {}) {
+    const query = {};
+    if (params.status) query.status = params.status;
+    if (params.payerEmail) query.payer_email = params.payerEmail;
+    if (params.externalReference) query.external_reference = params.externalReference;
+    if (params.preapproval_plan_id) query.preapproval_plan_id = params.preapproval_plan_id;
+    if (params.limit !== void 0) query.limit = params.limit;
+    if (params.offset !== void 0) query.offset = params.offset;
+    const result = await this.request("GET", "/preapproval/search", void 0, { query });
+    return {
+      results: result.results ?? [],
+      paging: result.paging ?? { limit: params.limit ?? 25, offset: params.offset ?? 0, total: 0 }
+    };
+  }
+  // ──────────────────────────────────────────────────────────────────────────
+  // v0.7 — Merchant Orders (parent of Payments grouped under a Preference)
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * Get a merchant_order with all its associated payments + shipments.
+   * Useful for reconciling "which payments belong to which preference"
+   * — typical webhook handler use case.
+   */
+  async getMerchantOrder(id) {
+    return this.request("GET", `/merchant_orders/${id}`);
+  }
+  /**
+   * Search merchant_orders by external_reference, preference_id, or status.
+   */
+  async searchMerchantOrders(params = {}) {
+    const query = {};
+    if (params.preferenceId) query.preference_id = params.preferenceId;
+    if (params.externalReference) query.external_reference = params.externalReference;
+    if (params.status) query.status = params.status;
+    if (params.limit !== void 0) query.limit = params.limit;
+    if (params.offset !== void 0) query.offset = params.offset;
+    const result = await this.request("GET", "/merchant_orders/search", void 0, { query });
+    return {
+      elements: result.elements ?? [],
+      paging: result.paging ?? { limit: params.limit ?? 25, offset: params.offset ?? 0, total: 0 }
+    };
+  }
+  /**
+   * Update a merchant_order — typically to add items or update shipping.
+   */
+  async updateMerchantOrder(id, patch) {
+    return this.request("PUT", `/merchant_orders/${id}`, patch);
+  }
+  // ──────────────────────────────────────────────────────────────────────────
+  // v0.7 — Stores + POS CRUD completion
+  // ──────────────────────────────────────────────────────────────────────────
+  async getStore(userId, storeId) {
+    return this.request("GET", `/users/${userId}/stores/${storeId}`);
+  }
+  async updateStore(userId, storeId, patch) {
+    return this.request("PUT", `/users/${userId}/stores/${storeId}`, patch);
+  }
+  async deleteStore(userId, storeId) {
+    await this.request("DELETE", `/users/${userId}/stores/${storeId}`);
+  }
+  async getPos(posId) {
+    return this.request("GET", `/pos/${posId}`);
+  }
+  async updatePos(posId, patch) {
+    return this.request("PUT", `/pos/${posId}`, patch);
+  }
+  async deletePos(posId) {
+    await this.request("DELETE", `/pos/${posId}`);
+  }
+  // ──────────────────────────────────────────────────────────────────────────
+  // v0.7 — Bank Accounts (the CBUs the seller has registered for payouts)
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * List bank accounts registered by the seller. The default is the one
+   * that receives `release_money` settlements.
+   */
+  async listBankAccounts() {
+    const result = await this.request(
+      "GET",
+      "/users/me/bank_accounts"
+    );
+    if (Array.isArray(result)) return result;
+    return result.results ?? [];
+  }
+  /**
+   * Register a new bank account (CBU) for the seller. Note: MP usually
+   * requires this through the dashboard for compliance — this endpoint may
+   * not work for all sellers.
+   */
+  async registerBankAccount(params) {
+    return this.request("POST", "/users/me/bank_accounts", params);
+  }
+  // ──────────────────────────────────────────────────────────────────────────
+  // v0.7 — Point Devices (physical terminal hardware: Smart, Tap to Pay)
+  //
+  // Distinct from the logical `Pos` entity. PointDevices are the actual
+  // physical terminals you have at brick-and-mortar shops.
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * List the Point devices linked to the seller's MP account. Each device
+   * has an id (the device serial), an operating_mode (PDV vs STANDALONE),
+   * and an optional pos_id (when bound to a logical POS).
+   */
+  async listPointDevices(params = {}) {
+    const query = {};
+    if (params.posId !== void 0) query["pos.id"] = params.posId;
+    if (params.limit !== void 0) query.limit = params.limit;
+    if (params.offset !== void 0) query.offset = params.offset;
+    const result = await this.request("GET", "/point/integration-api/devices", void 0, { query });
+    return {
+      devices: result.devices ?? [],
+      paging: result.paging ?? { total: 0, limit: params.limit ?? 50, offset: params.offset ?? 0 }
+    };
+  }
+  /**
+   * Switch a Point device's operating mode:
+   * - "PDV": device is bound to a logical Pos and only takes payments
+   *   triggered through that Pos (typical for cash-register integrations).
+   * - "STANDALONE": device works independently, accepts any payment.
+   */
+  async updatePointDeviceOperatingMode(deviceId, operatingMode) {
+    return this.request(
+      "PATCH",
+      `/point/integration-api/devices/${encodeURIComponent(deviceId)}`,
+      { operating_mode: operatingMode }
+    );
+  }
+  /**
+   * Create a payment intent on a Point device — the device prompts the buyer
+   * to tap/insert/swipe. Returns immediately with intent id; query state via
+   * `getPointPaymentIntent()` or wait for `point_integration_wh` webhook.
+   *
+   * NOTE: amount is in CENTAVOS (Point API differs from Payments API which
+   * uses pesos). 100 = $1 ARS, 1000 = $10, 10000 = $100, etc.
+   */
+  async createPointPaymentIntent(deviceId, params) {
+    const body = {
+      amount: params.amount,
+      ...params.description ? { description: params.description } : {},
+      ...params.externalReference ? { additional_info: { external_reference: params.externalReference } } : {},
+      payment: {
+        installments: params.installments ?? 1,
+        ...params.installmentsCost ? { installments_cost: params.installmentsCost } : {},
+        ...params.printOnTerminal !== void 0 ? { print_on_terminal: params.printOnTerminal } : {},
+        ...params.ticketNumber ? { ticket_number: params.ticketNumber } : {}
+      }
+    };
+    return this.request(
+      "POST",
+      `/point/integration-api/devices/${encodeURIComponent(deviceId)}/payment-intents`,
+      body
+    );
+  }
+  /** Get the current state of a Point payment intent. */
+  async getPointPaymentIntent(intentId) {
+    return this.request(
+      "GET",
+      `/point/integration-api/payment-intents/${encodeURIComponent(intentId)}`
+    );
+  }
+  /**
+   * Cancel an OPEN payment intent before the buyer interacts with the device.
+   * Only works while state is "OPEN" — once the buyer taps, you can't cancel.
+   */
+  async cancelPointPaymentIntent(deviceId, intentId) {
+    await this.request(
+      "DELETE",
+      `/point/integration-api/devices/${encodeURIComponent(deviceId)}/payment-intents/${encodeURIComponent(intentId)}`
+    );
+    return { id: intentId, canceled: true };
+  }
 };
 zod.z.enum(["MLA", "MLB", "MLM", "MCO", "MLC", "MLU"]);
 var CurrencyIdSchema = zod.z.enum(["ARS", "USD", "BRL", "MXN"]);
@@ -1308,6 +1582,95 @@ zod.z.object({
   /** Capture mode: "automatic" (charges immediately) or "manual" (auth-only). */
   capture_mode: zod.z.string().optional()
 }).passthrough();
+zod.z.object({
+  user_id: zod.z.union([zod.z.string(), zod.z.number()]).transform(String).optional(),
+  available_balance: zod.z.number(),
+  unavailable_balance: zod.z.number(),
+  total_amount: zod.z.number(),
+  currency_id: zod.z.string().default("ARS")
+}).passthrough();
+zod.z.object({
+  id: zod.z.union([zod.z.string(), zod.z.number()]).transform(String),
+  type: zod.z.string(),
+  description: zod.z.string().optional(),
+  amount: zod.z.number(),
+  currency_id: zod.z.string().optional(),
+  status: zod.z.string().optional(),
+  date_created: zod.z.string().optional(),
+  date_released: zod.z.string().optional(),
+  reference_id: zod.z.union([zod.z.string(), zod.z.number()]).optional(),
+  payment_id: zod.z.union([zod.z.string(), zod.z.number()]).optional()
+}).passthrough();
+zod.z.object({
+  id: zod.z.union([zod.z.string(), zod.z.number()]).transform(String),
+  status: zod.z.string().optional(),
+  amount: zod.z.number().optional(),
+  currency_id: zod.z.string().optional(),
+  date_created: zod.z.string().optional(),
+  date_scheduled: zod.z.string().optional(),
+  date_processed: zod.z.string().optional(),
+  bank_account: zod.z.object({
+    cbu: zod.z.string().optional(),
+    bank_name: zod.z.string().optional()
+  }).passthrough().optional()
+}).passthrough();
+zod.z.object({
+  id: zod.z.union([zod.z.string(), zod.z.number()]).transform(String),
+  status: zod.z.string().optional(),
+  external_reference: zod.z.string().nullable().optional(),
+  preference_id: zod.z.union([zod.z.string(), zod.z.number()]).optional(),
+  payments: zod.z.array(zod.z.unknown()).optional(),
+  shipments: zod.z.array(zod.z.unknown()).optional(),
+  payer: zod.z.unknown().optional(),
+  collector: zod.z.unknown().optional(),
+  marketplace: zod.z.string().optional(),
+  total_amount: zod.z.number().optional(),
+  paid_amount: zod.z.number().optional(),
+  refunded_amount: zod.z.number().optional(),
+  shipping_cost: zod.z.number().optional(),
+  date_created: zod.z.string().optional(),
+  last_updated: zod.z.string().optional(),
+  site_id: zod.z.string().optional(),
+  order_status: zod.z.string().optional()
+}).passthrough();
+zod.z.object({
+  id: zod.z.union([zod.z.string(), zod.z.number()]).transform(String),
+  cbu: zod.z.string().optional(),
+  alias: zod.z.string().nullable().optional(),
+  bank_name: zod.z.string().optional(),
+  account_type: zod.z.string().optional(),
+  status: zod.z.string().optional(),
+  is_default: zod.z.boolean().optional(),
+  date_created: zod.z.string().optional()
+}).passthrough();
+zod.z.object({
+  id: zod.z.string(),
+  pos_id: zod.z.union([zod.z.string(), zod.z.number()]).nullable().optional(),
+  store_id: zod.z.union([zod.z.string(), zod.z.number()]).nullable().optional(),
+  external_pos_id: zod.z.string().nullable().optional(),
+  operating_mode: zod.z.union([zod.z.literal("PDV"), zod.z.literal("STANDALONE"), zod.z.string()]).optional()
+}).passthrough();
+zod.z.object({
+  id: zod.z.string(),
+  device_id: zod.z.string().optional(),
+  amount: zod.z.number().optional(),
+  state: zod.z.union([
+    zod.z.literal("OPEN"),
+    zod.z.literal("PROCESSING"),
+    zod.z.literal("FINISHED"),
+    zod.z.literal("CANCELED"),
+    zod.z.literal("ERROR"),
+    zod.z.string()
+  ]).optional(),
+  payment: zod.z.object({
+    id: zod.z.union([zod.z.string(), zod.z.number()]).optional(),
+    type: zod.z.string().optional(),
+    installments: zod.z.number().optional(),
+    installments_cost: zod.z.string().optional(),
+    print_on_terminal: zod.z.boolean().optional()
+  }).passthrough().optional(),
+  additional_info: zod.z.unknown().optional()
+}).passthrough();
 
 // src/oauth.ts
 var DEFAULT_AUTHORIZE_URL = "https://auth.mercadopago.com.ar/authorization";
@@ -1374,6 +1737,371 @@ function expirationTimeMs(issuedAtMs, expiresInSeconds) {
 function isExpiringSoon(expirationMs, skewSeconds = 300) {
   return Date.now() + skewSeconds * 1e3 >= expirationMs;
 }
+
+// src/helpers.ts
+function computeMarketplaceFee(amountArs, rule) {
+  if (amountArs <= 0) return 0;
+  const percentPart = (rule.percent ?? 0) > 0 ? amountArs * (rule.percent / 100) : 0;
+  const flatPart = rule.flatArs ?? 0;
+  let fee = percentPart + flatPart;
+  if (rule.minArs !== void 0) fee = Math.max(fee, rule.minArs);
+  if (rule.maxArs !== void 0) fee = Math.min(fee, rule.maxArs);
+  if (fee > amountArs) fee = amountArs;
+  if (rule.round !== false) fee = Math.round(fee);
+  return fee;
+}
+var STATUS_DETAIL_MAP = {
+  // Approved
+  accredited: {
+    summary: "Pago aprobado y acreditado.",
+    recommendedAction: "Confirmar al cliente y continuar con el flujo (env\xEDo, factura).",
+    retryable: false
+  },
+  partially_refunded: {
+    summary: "Pago aprobado con reembolso parcial.",
+    recommendedAction: "Mostrar el monto neto y el reembolso. Verificar inventario si corresponde.",
+    retryable: false
+  },
+  // Pending
+  pending_contingency: {
+    summary: "Pago en proceso por contingencia. MP est\xE1 procesando \u2014 puede demorar minutos a horas.",
+    recommendedAction: "No reintentar todav\xEDa. Esperar webhook de actualizaci\xF3n (puede demorar 24h m\xE1x).",
+    retryable: false
+  },
+  pending_review_manual: {
+    summary: "Pago en revisi\xF3n manual por el equipo de seguridad de MP.",
+    recommendedAction: "No reintentar. MP responder\xE1 con webhook en 24-72h. Avisar al cliente sobre la demora.",
+    retryable: false
+  },
+  pending_waiting_payment: {
+    summary: "Esperando que el comprador complete el pago (t\xEDpico de account_money / boleto / Rapipago).",
+    recommendedAction: "Mostrar instrucciones de pago. MP avisar\xE1 por webhook cuando se complete.",
+    retryable: false
+  },
+  pending_waiting_transfer: {
+    summary: "Esperando confirmaci\xF3n de transferencia bancaria.",
+    recommendedAction: "Esperar webhook. Sin acci\xF3n del agente.",
+    retryable: false
+  },
+  pending_challenge: {
+    summary: "El emisor de la tarjeta requiri\xF3 autenticaci\xF3n 3DS. El comprador debe completar el desaf\xEDo.",
+    recommendedAction: "Redirigir al comprador a `payment.three_ds_info.external_resource_url` (us\xE1 analyze_payment_3ds para obtenerlo).",
+    retryable: false
+  },
+  // Rejected — RETRYABLE (user can fix and try again)
+  cc_rejected_bad_filled_card_number: {
+    summary: "El n\xFAmero de tarjeta es incorrecto.",
+    recommendedAction: "Pedir al cliente que verifique el n\xFAmero. Reintentable.",
+    retryable: true
+  },
+  cc_rejected_bad_filled_security_code: {
+    summary: "El CVV es incorrecto.",
+    recommendedAction: "Pedir el CVV nuevamente. Reintentable.",
+    retryable: true
+  },
+  cc_rejected_bad_filled_date: {
+    summary: "La fecha de vencimiento es incorrecta.",
+    recommendedAction: "Pedir al cliente que verifique mes/a\xF1o. Reintentable.",
+    retryable: true
+  },
+  cc_rejected_bad_filled_other: {
+    summary: "Alg\xFAn dato de la tarjeta es incorrecto.",
+    recommendedAction: "Pedir al cliente que revise todos los datos. Reintentable.",
+    retryable: true
+  },
+  cc_rejected_call_for_authorize: {
+    summary: "El emisor requiere que el cliente autorice el pago llamando al banco.",
+    recommendedAction: "Mostrar el tel\xE9fono del banco emisor (us\xE1 list_issuers para obtenerlo). Reintentable despu\xE9s de la llamada.",
+    retryable: true
+  },
+  cc_rejected_card_disabled: {
+    summary: "La tarjeta est\xE1 inhabilitada por el banco emisor.",
+    recommendedAction: "El cliente debe contactar a su banco. Probar con otra tarjeta. Reintentable con otra tarjeta.",
+    retryable: true
+  },
+  cc_rejected_insufficient_amount: {
+    summary: "Saldo insuficiente en la tarjeta.",
+    recommendedAction: "Sugerir tarjeta alternativa o monto menor. Reintentable.",
+    retryable: true
+  },
+  cc_rejected_invalid_installments: {
+    summary: "El emisor no soporta esa cantidad de cuotas para esta tarjeta.",
+    recommendedAction: "Llamar a calculate_installments para ver opciones v\xE1lidas y sugerir otra. Reintentable.",
+    retryable: true
+  },
+  cc_rejected_other_reason: {
+    summary: "Pago rechazado por raz\xF3n no especificada del emisor.",
+    recommendedAction: "Sugerir otra tarjeta o m\xE9todo de pago. Reintentable con otra tarjeta.",
+    retryable: true
+  },
+  // Rejected — NON-RETRYABLE (don't retry the same card)
+  cc_rejected_blacklist: {
+    summary: "Pago rechazado por blacklist de seguridad de MP. NO REINTENTAR con esta tarjeta.",
+    recommendedAction: "Sugerir un m\xE9todo de pago alternativo (account_money, otra tarjeta de otro titular).",
+    retryable: false
+  },
+  cc_rejected_high_risk: {
+    summary: "Rechazo por an\xE1lisis de riesgo de MP. La tarjeta es v\xE1lida pero MP detect\xF3 fraude potencial.",
+    recommendedAction: "Sugerir otro medio de pago o pedirle al cliente que verifique su identidad en MP.",
+    retryable: false
+  },
+  cc_rejected_max_attempts: {
+    summary: "Excedi\xF3 el n\xFAmero m\xE1ximo de intentos con esta tarjeta.",
+    recommendedAction: "Pedir al cliente que use otra tarjeta. NO REINTENTAR la misma.",
+    retryable: false
+  },
+  cc_rejected_duplicated_payment: {
+    summary: "Ya se proces\xF3 un pago id\xE9ntico en los \xFAltimos minutos (deduplicaci\xF3n de MP).",
+    recommendedAction: "Verificar con search_payments si el pago anterior se acredit\xF3. Sin acci\xF3n adicional necesaria.",
+    retryable: false
+  },
+  // Cancelled / refunded / mediation
+  by_collector: {
+    summary: "El vendedor cancel\xF3 el pago.",
+    recommendedAction: "Sin acci\xF3n. Estado final.",
+    retryable: false
+  },
+  by_payer: {
+    summary: "El comprador cancel\xF3 el pago.",
+    recommendedAction: "Sin acci\xF3n. Estado final.",
+    retryable: false
+  },
+  refunded: {
+    summary: "Pago reembolsado al comprador.",
+    recommendedAction: "Estado final. Reflejar el reembolso en tu sistema.",
+    retryable: false
+  },
+  charged_back: {
+    summary: "Contracargo (chargeback) iniciado por el banco emisor.",
+    recommendedAction: "Revisar list_payment_disputes para responder. Surface al equipo de ops.",
+    retryable: false
+  }
+};
+function explainPaymentStatus(payment) {
+  const status = payment.status;
+  const statusDetail = payment.status_detail ?? "";
+  const detail = STATUS_DETAIL_MAP[statusDetail];
+  if (detail) {
+    const isFinal = status === "approved" || status === "rejected" || status === "cancelled" || status === "refunded" || status === "charged_back";
+    return {
+      summary: detail.summary,
+      recommendedAction: detail.recommendedAction,
+      final: isFinal,
+      paid: status === "approved",
+      retryable: detail.retryable
+    };
+  }
+  switch (status) {
+    case "approved":
+      return {
+        summary: "Pago aprobado.",
+        recommendedAction: "Continuar con el flujo posterior (env\xEDo, factura, notificaci\xF3n).",
+        final: true,
+        paid: true,
+        retryable: false
+      };
+    case "authorized":
+      return {
+        summary: "Pago autorizado pero no capturado (auth-only).",
+        recommendedAction: "Llamar a capture_payment cuando complet\xE9s el servicio. Vence en 7 d\xEDas si no captur\xE1s.",
+        final: false,
+        paid: false,
+        retryable: false
+      };
+    case "in_process":
+      return {
+        summary: "Pago en proceso.",
+        recommendedAction: "Esperar webhook. Sin acci\xF3n inmediata.",
+        final: false,
+        paid: false,
+        retryable: false
+      };
+    case "in_mediation":
+      return {
+        summary: "Pago en mediaci\xF3n con MP por disputa del comprador.",
+        recommendedAction: "Revisar list_payment_disputes y responder via dashboard.",
+        final: false,
+        paid: false,
+        retryable: false
+      };
+    case "pending":
+      return {
+        summary: "Pago pendiente. El comprador no complet\xF3 el pago todav\xEDa o MP est\xE1 procesando.",
+        recommendedAction: "Esperar webhook (puede demorar minutos a 72h seg\xFAn el m\xE9todo).",
+        final: false,
+        paid: false,
+        retryable: false
+      };
+    case "rejected":
+      return {
+        summary: `Pago rechazado (status_detail: ${statusDetail || "no especificado"}).`,
+        recommendedAction: "Verificar status_detail. Considerar otro m\xE9todo de pago.",
+        final: true,
+        paid: false,
+        retryable: true
+      };
+    case "cancelled":
+      return {
+        summary: "Pago cancelado.",
+        recommendedAction: "Estado final. Sin acci\xF3n.",
+        final: true,
+        paid: false,
+        retryable: false
+      };
+    case "refunded":
+      return {
+        summary: "Pago reembolsado.",
+        recommendedAction: "Estado final. Reflejar el reembolso.",
+        final: true,
+        paid: false,
+        retryable: false
+      };
+    case "charged_back":
+      return {
+        summary: "Pago con contracargo del banco.",
+        recommendedAction: "Surfacear a ops. Revisar disputas.",
+        final: true,
+        paid: false,
+        retryable: false
+      };
+    default:
+      return {
+        summary: `Status no reconocido: '${status}'.`,
+        recommendedAction: "Inspeccionar payment.status + payment.status_detail manualmente.",
+        final: false,
+        paid: false,
+        retryable: false
+      };
+  }
+}
+
+// src/test-cards.ts
+var TEST_CARDS_AR = {
+  VISA_CREDIT: {
+    brand: "Visa (cr\xE9dito)",
+    number: "4509 9535 6623 3704".replace(/\s/g, ""),
+    cvv: "123",
+    exp: "11/30",
+    paymentMethodId: "visa",
+    holderNameToTest: {
+      APRO: "approved",
+      OTHE: "cc_rejected_other_reason",
+      CONT: "pending_contingency",
+      CALL: "cc_rejected_call_for_authorize",
+      FUND: "cc_rejected_insufficient_amount",
+      SECU: "cc_rejected_bad_filled_security_code",
+      EXPI: "cc_rejected_bad_filled_date",
+      FORM: "cc_rejected_bad_filled_other"
+    }
+  },
+  MASTERCARD_CREDIT: {
+    brand: "Mastercard (cr\xE9dito)",
+    number: "5031 7557 3453 0604".replace(/\s/g, ""),
+    cvv: "123",
+    exp: "11/30",
+    paymentMethodId: "master",
+    holderNameToTest: {
+      APRO: "approved",
+      OTHE: "cc_rejected_other_reason",
+      CONT: "pending_contingency",
+      CALL: "cc_rejected_call_for_authorize",
+      FUND: "cc_rejected_insufficient_amount"
+    }
+  },
+  AMEX_CREDIT: {
+    brand: "American Express (cr\xE9dito)",
+    number: "3711 803032 57522".replace(/\s/g, ""),
+    cvv: "1234",
+    exp: "11/30",
+    paymentMethodId: "amex",
+    holderNameToTest: { APRO: "approved", OTHE: "cc_rejected_other_reason" }
+  },
+  VISA_DEBIT: {
+    brand: "Visa (d\xE9bito)",
+    number: "4002 7686 9439 5619".replace(/\s/g, ""),
+    cvv: "123",
+    exp: "11/30",
+    paymentMethodId: "debvisa",
+    holderNameToTest: { APRO: "approved", OTHE: "cc_rejected_other_reason" }
+  },
+  MASTERCARD_DEBIT: {
+    brand: "Mastercard (d\xE9bito)",
+    number: "5287 3383 0125 4634".replace(/\s/g, ""),
+    cvv: "123",
+    exp: "11/30",
+    paymentMethodId: "debmaster",
+    holderNameToTest: { APRO: "approved", OTHE: "cc_rejected_other_reason" }
+  }
+};
+var TEST_PAYERS_AR = {
+  approvedBuyer: () => ({
+    email: `test_user_${Date.now()}@testuser.com`,
+    identification: { type: "DNI", number: "12345678" }
+  })
+};
+function buildTestCardScenario(cardKey, scenario, amountArs) {
+  const card = TEST_CARDS_AR[cardKey];
+  if (!card) throw new Error(`Unknown test card: ${cardKey}`);
+  if (!card.holderNameToTest[scenario]) {
+    throw new Error(
+      `Card ${cardKey} doesn't define scenario ${scenario}. Available: ${Object.keys(card.holderNameToTest).join(", ")}`
+    );
+  }
+  return {
+    transactionAmount: amountArs,
+    paymentMethodId: card.paymentMethodId,
+    payerEmail: TEST_PAYERS_AR.approvedBuyer().email,
+    description: `TEST ${scenario} via ${cardKey}`,
+    installments: 1,
+    holderName: scenario
+  };
+}
+
+// src/three-ds.ts
+function analyze3DS(payment) {
+  const raw = payment;
+  const mode = raw.three_d_secure_mode ?? null;
+  const statusDetail = payment.status_detail ?? null;
+  if (!mode || mode === "not_supported" || mode === "off") {
+    return {
+      status: "not_required",
+      mode,
+      challengeUrl: null,
+      description: "3DS no fue requerido para este pago (riesgo bajo o emisor sin 3DS habilitado)."
+    };
+  }
+  const threeDsInfo = raw.three_ds_info ?? void 0;
+  if (statusDetail === "pending_challenge" && threeDsInfo?.external_resource_url) {
+    return {
+      status: "challenge_required",
+      mode,
+      challengeUrl: threeDsInfo.external_resource_url,
+      description: "El emisor de la tarjeta requiri\xF3 autenticaci\xF3n 3DS. Redirig\xED al comprador a challengeUrl para completar el desaf\xEDo. El pago queda pending hasta que lo haga."
+    };
+  }
+  if (payment.status === "approved") {
+    return {
+      status: "frictionless",
+      mode,
+      challengeUrl: null,
+      description: "3DS frictionless: el emisor autoriz\xF3 sin desafiar al comprador."
+    };
+  }
+  if (payment.status === "rejected" && typeof statusDetail === "string" && statusDetail.includes("3ds")) {
+    return {
+      status: "rejected",
+      mode,
+      challengeUrl: null,
+      description: `Autenticaci\xF3n 3DS rechazada (${statusDetail}). El comprador debe usar otra tarjeta o validarla con el emisor.`
+    };
+  }
+  return {
+    status: "unknown",
+    mode,
+    challengeUrl: threeDsInfo?.external_resource_url ?? null,
+    description: "No se pudo determinar el estado 3DS \u2014 revisar payment.three_d_secure_mode + payment.status_detail manualmente."
+  };
+}
 function parseWebhookEvent(body, searchParams) {
   const parseResult = WebhookBodySchema.safeParse(body ?? {});
   const parsedBody = parseResult.success ? parseResult.data : {};
@@ -1475,7 +2203,50 @@ var DEFAULT_DESCRIPTIONS = {
   get_order: "Fetch an Order by ID. Returns the Order with its lifecycle status and any attached payments/refunds.",
   update_order: "Patch an existing Order before it's captured/canceled. Common use: update items or external_reference.",
   capture_order: "Capture a previously-authorized Order (only for orders created with capture_mode='manual'). Captures up to the originally-authorized amount; pass amount for partial capture. Common use: ride-share marks ride complete \u2192 capture; hotel checks-out guest \u2192 capture.",
-  cancel_order: "Cancel an Order. Releases any auth-holds and marks the Order as canceled. For orders that have already been CAPTURED, use refund_payment instead \u2014 cancel only works pre-capture."
+  cancel_order: "Cancel an Order. Releases any auth-holds and marks the Order as canceled. For orders that have already been CAPTURED, use refund_payment instead \u2014 cancel only works pre-capture.",
+  // ── Account / Balance / Movements / Settlements (v0.6) ───────────────────
+  get_account_balance: "Get the seller's current MP wallet balance. Returns { available_balance, unavailable_balance, total_amount, currency_id }. The available balance is what the seller can withdraw or pay with right now; unavailable is in retention (typically 14-21 days for new sellers or risk-flagged transactions). For per-seller marketplace setups, instantiate the client AS THE SELLER first.",
+  list_account_movements: "List wallet movements (incoming payments, transfers, refunds, holdings) for the active MP account. Filter by date range with `from`/`to` (ISO 8601). Useful for monthly conciliation or 'show me what came in this month' workflows.",
+  list_settlements: "List settlements (release_money) \u2014 i.e. transfers from the MP wallet to the seller's registered bank account (CBU). USE WHEN the user asks 'cu\xE1ndo me deposita MP' or for monthly bank-conciliation reports. Filter by date range and status.",
+  get_settlement: "Get details of a single settlement: amount, date_scheduled, date_processed, bank_account info (CBU + bank name).",
+  // ── 3DS analyzer (v0.6 — pure) ───────────────────────────────────────────
+  analyze_payment_3ds: "Pure local analyzer for a Payment's 3DS (Strong Customer Authentication) state. Pass a payment_id (string) and the tool fetches the Payment then derives { status: 'not_required'|'frictionless'|'challenge_required'|'rejected'|'unknown', mode, challengeUrl, description }. USE THIS after every create_payment for credit cards: when challengeUrl !== null, you MUST redirect the buyer there before the payment can complete. Without 3DS, payments stay in 'pending' indefinitely if the issuer demanded a challenge.",
+  // ── Test cards (v0.6 — pure) ─────────────────────────────────────────────
+  get_test_cards: "Pure helper that returns the official MP test cards for AR (MLA): VISA/Mastercard/Amex credit + debit, with the 'magic' holder names that route the payment to specific status_detail values (APRO=approved, OTHE=rejected, CONT=pending, FUND=insufficient_amount, etc.). USE WHEN you need to demo a payment flow without a real card, or to script integration tests. Pure data \u2014 no network call.",
+  // ── Customer + Card extensions (v0.7) ────────────────────────────────────
+  get_customer: "Get a customer by id. Returns full Customer object: email, first_name, last_name, identification, address, default_card, registered cards. PURE READ. USE WHEN you have the customer_id from a previous create_customer / find_customer_by_email / payment.payer.id and want the full record.",
+  update_customer: "Update a customer's profile (first_name, last_name, phone, identification, address, default_card). MP merges the patch \u2014 fields you don't send remain unchanged. Use to keep customer records in sync (e.g., shipping address changes) or to set a default card for charge_saved_card.",
+  create_customer_card: "Add a saved card to an existing customer using a card_token (one-time token from MP frontend Cardform \u2014 agents should NEVER take raw card data, that's a PCI violation). Returns the saved CustomerCard with id usable in charge_saved_card. Persists across charges (no need to re-tokenize each time).",
+  get_customer_card: "Get details of a single saved card by (customer_id, card_id). Returns last 4 digits, expiration, brand, issuer. PURE READ \u2014 useful before charge_saved_card to confirm the card is still valid.",
+  // ── Subscription / Plan / Refund / Preference extensions (v0.7) ─────────
+  get_subscription_plan: "Fetch a subscription plan by id. Returns plan config: amount, frequency, status, init_point. Use to inspect a plan before subscribing customers, or to display plan details to the user.",
+  update_subscription: "Update a subscription's amount, status, reason, external_reference, OR card_token_id (to switch payment method when the buyer's card is expired/declined). For card swap: pass card_token_id from a fresh tokenization. CONSTRAINTS: status changes only support 'paused' | 'cancelled' (use authorize via init_point flow to re-activate).",
+  search_subscriptions: "Search subscriptions across the seller's account. Filter by status (pending/authorized/paused/cancelled), payer_email, external_reference, or preapproval_plan_id (to find all subscribers of a plan). Paginated. USE WHEN you need to enumerate active subscribers, audit cancellations, or find a subscription by external reference.",
+  get_refund: "Fetch a single refund by (payment_id, refund_id). Returns the Refund object with amount, status, date_created. PURE READ \u2014 useful to verify a refund processed or to reconcile partial-refund history.",
+  update_payment_preference: "Update a Checkout Pro preference (notification_url, back_urls, items, payer info, payment_methods exclusion list). Only works on preferences NOT yet paid. Common use: regenerate the link with a new notification_url after deployment, or change items if the buyer requested adjustments before paying.",
+  // ── Merchant Orders (v0.7) ────────────────────────────────────────────────
+  get_merchant_order: "Get a merchant_order with all its associated payments + shipments. MerchantOrder is the parent entity for Payments associated with a single Preference \u2014 one Order can have multiple partial Payments (retries, installments). USE THIS in webhooks with topic='merchant_order' to get the aggregate paid_amount, refunded_amount, and shipping status in one call.",
+  search_merchant_orders: "Search merchant_orders by preference_id, external_reference, or status. Paginated. Returns up to 50 per page. USE WHEN you have a preference_id and want all its derived merchant_orders, or when reconciling 'which payments belong to which preference'.",
+  update_merchant_order: "Update a merchant_order \u2014 typically to add items or shipping info. Most agent flows don't need this; use only when integrating with a custom shipping flow that requires updating the MO mid-lifecycle.",
+  // ── Stores + POS CRUD completion (v0.7) ──────────────────────────────────
+  get_store: "Fetch a single store by (user_id, store_id). Returns store details: name, location, business_hours, external_id. PURE READ.",
+  update_store: "Update a store's properties (name, location, business_hours, external_id). MP merges the patch.",
+  delete_store: "Delete a store. IRREVERSIBLE. Confirm with user before calling. Will fail if the store has associated POSes \u2014 delete those first.",
+  get_pos: "Fetch a POS by id. Returns: name, store_id, category, external_id, qr_template (if configured). PURE READ. Use when you need to find the external_id for create_qr_payment.",
+  update_pos: "Update a POS's properties (name, category, external_id). MP merges the patch.",
+  delete_pos: "Delete a POS. IRREVERSIBLE. Cancels any pending QR orders attached to it. Confirm with user before calling.",
+  // ── Bank Accounts (v0.7) ─────────────────────────────────────────────────
+  list_bank_accounts: "List the bank accounts (CBUs) the seller has registered with MP for receiving payouts. Returns an array \u2014 the one with `is_default: true` is where settlements (release_money) go. USE BEFORE list_settlements when the user asks 'a qu\xE9 cuenta me deposita MP'.",
+  register_bank_account: "Register a new bank account (CBU) for the seller. NOTE: MP usually requires this through the dashboard for compliance \u2014 this endpoint may not work for all accounts. If it fails with 403, redirect the user to https://www.mercadopago.com.ar/banking/dashboard.",
+  // ── Point Devices físicos (v0.7) ─────────────────────────────────────────
+  list_point_devices: "List the physical Point devices (Smart, Tap to Pay, etc.) linked to the seller's MP account. Distinct from logical POS \u2014 these are actual terminals at brick-and-mortar shops. Returns each device's id (serial), operating_mode (PDV vs STANDALONE), and pos_id (when bound to a logical POS). Filter by pos_id to find devices for a specific cash register.",
+  update_point_device_mode: "Switch a Point device's operating_mode between 'PDV' (bound to a logical POS, takes payments triggered through that POS) and 'STANDALONE' (works independently, accepts any payment). PDV is for cash-register integrations; STANDALONE is for free-form retail. Affects how payments hit the device.",
+  create_point_payment_intent: "Create a payment intent on a physical Point device \u2014 the device prompts the buyer to tap/insert/swipe their card. Returns immediately with intent_id; query state via get_point_payment_intent or wait for point_integration_wh webhook. **AMOUNT IS IN CENTAVOS**, NOT pesos (Point API differs from Payments API): 100 = $1, 1000 = $10, 10000 = $100.",
+  get_point_payment_intent: "Get the current state of a Point payment intent (OPEN, PROCESSING, FINISHED, CANCELED, ERROR). USE in polling loops if you can't wait for the webhook. When state=FINISHED, the intent.payment.id is the resulting Payment id usable with get_payment.",
+  cancel_point_payment_intent: "Cancel an OPEN point payment intent before the buyer interacts with the device. ONLY WORKS while state='OPEN' \u2014 once the buyer taps, you can't cancel; refund_payment after the fact instead.",
+  // ── Pure helpers (v0.7) ──────────────────────────────────────────────────
+  compute_marketplace_fee: "PURE HELPER (no network) \u2014 given a transaction amount + fee rule (% or flat ARS, with optional min/max floors), returns the exact `marketplace_fee` value in ARS to pass to create_order or create_payment_preference. USE WHEN your platform takes a commission and you need to compute the exact fee per transaction. Examples: { percent: 5, minArs: 50, maxArs: 5000 } for percentage with floor + cap; { flatArs: 200, percent: 2 } for fixed + percentage.",
+  explain_payment_status: "PURE HELPER (no network) \u2014 given a Payment object (from get_payment / create_payment / handle_webhook), returns { summary, recommendedAction, final, paid, retryable } in Spanish. Translates MP's cryptic status_detail codes to plain Spanish + actionable guidance ('reintentar con otra tarjeta' vs 'esperar webhook' vs 'estado final'). USE THIS instead of having to memorize 30+ status_detail codes \u2014 surface summary + recommendedAction directly to the user."
 };
 function mercadoPagoTools(client, options) {
   const desc = (name) => options.descriptions?.[name] ?? DEFAULT_DESCRIPTIONS[name];
@@ -2782,6 +3553,483 @@ function mercadoPagoTools(client, options) {
           status: order.status ?? "canceled"
         };
       }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.6 — Account / Balance / Movements / Settlements
+    // ─────────────────────────────────────────────────────────────────────────
+    get_account_balance: ai.tool({
+      description: desc("get_account_balance"),
+      inputSchema: zod.z.object({}),
+      execute: async () => {
+        const balance = await client.getAccountBalance();
+        return balance;
+      }
+    }),
+    list_account_movements: ai.tool({
+      description: desc("list_account_movements"),
+      inputSchema: zod.z.object({
+        from: zod.z.string().optional().describe("ISO 8601 start date (e.g. 2026-05-01)"),
+        to: zod.z.string().optional().describe("ISO 8601 end date"),
+        limit: zod.z.number().int().min(1).max(100).optional(),
+        offset: zod.z.number().int().min(0).optional()
+      }),
+      execute: async ({ from, to, limit, offset }) => {
+        const params = {};
+        if (from !== void 0) params.from = from;
+        if (to !== void 0) params.to = to;
+        if (limit !== void 0) params.limit = limit;
+        if (offset !== void 0) params.offset = offset;
+        return client.listAccountMovements(params);
+      }
+    }),
+    list_settlements: ai.tool({
+      description: desc("list_settlements"),
+      inputSchema: zod.z.object({
+        from: zod.z.string().optional(),
+        to: zod.z.string().optional(),
+        status: zod.z.string().optional(),
+        limit: zod.z.number().int().min(1).max(100).optional(),
+        offset: zod.z.number().int().min(0).optional()
+      }),
+      execute: async ({ from, to, status, limit, offset }) => {
+        const params = {};
+        if (from !== void 0) params.from = from;
+        if (to !== void 0) params.to = to;
+        if (status !== void 0) params.status = status;
+        if (limit !== void 0) params.limit = limit;
+        if (offset !== void 0) params.offset = offset;
+        return client.listSettlements(params);
+      }
+    }),
+    get_settlement: ai.tool({
+      description: desc("get_settlement"),
+      inputSchema: zod.z.object({ settlement_id: zod.z.string() }),
+      execute: async ({ settlement_id }) => {
+        return client.getSettlement(settlement_id);
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.6 — 3DS analyzer (combined: fetch payment + analyze)
+    // ─────────────────────────────────────────────────────────────────────────
+    analyze_payment_3ds: ai.tool({
+      description: desc("analyze_payment_3ds"),
+      inputSchema: zod.z.object({
+        payment_id: zod.z.string().describe("MP payment id")
+      }),
+      execute: async ({ payment_id }) => {
+        const payment = await client.getPayment(payment_id);
+        const info = analyze3DS(payment);
+        return {
+          payment_id,
+          payment_status: payment.status,
+          payment_status_detail: payment.status_detail ?? null,
+          ...info
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.6 — Test cards (pure)
+    // ─────────────────────────────────────────────────────────────────────────
+    get_test_cards: ai.tool({
+      description: desc("get_test_cards"),
+      inputSchema: zod.z.object({}),
+      execute: async () => {
+        return {
+          site: "MLA",
+          cards: TEST_CARDS_AR,
+          usage: "Pass holderName='APRO' for an approved payment, 'OTHE' for rejected, 'CONT' for pending, 'FUND' for insufficient amount, 'CALL' for call-for-authorize. Use a NEW payer email per call (append a timestamp) to avoid MP idempotency-on-email deduping."
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.7 — Customer + Card extensions
+    // ─────────────────────────────────────────────────────────────────────────
+    get_customer: ai.tool({
+      description: desc("get_customer"),
+      inputSchema: zod.z.object({ customer_id: zod.z.string() }),
+      execute: async ({ customer_id }) => {
+        return client.getCustomer(customer_id);
+      }
+    }),
+    update_customer: ai.tool({
+      description: desc("update_customer"),
+      inputSchema: zod.z.object({
+        customer_id: zod.z.string(),
+        first_name: zod.z.string().optional(),
+        last_name: zod.z.string().optional(),
+        phone: zod.z.object({ area_code: zod.z.string().optional(), number: zod.z.string().optional() }).optional(),
+        identification: zod.z.object({ type: zod.z.string(), number: zod.z.string() }).optional(),
+        address: zod.z.object({
+          street_name: zod.z.string().optional(),
+          street_number: zod.z.number().optional(),
+          zip_code: zod.z.string().optional()
+        }).optional(),
+        description: zod.z.string().optional(),
+        default_card: zod.z.string().optional()
+      }),
+      execute: async ({ customer_id, ...patch }) => {
+        const cleaned = {};
+        for (const [k, v] of Object.entries(patch)) {
+          if (v !== void 0) cleaned[k] = v;
+        }
+        return client.updateCustomer(customer_id, cleaned);
+      }
+    }),
+    create_customer_card: ai.tool({
+      description: desc("create_customer_card"),
+      inputSchema: zod.z.object({
+        customer_id: zod.z.string(),
+        card_token: zod.z.string().describe("Card token from MP frontend Cardform OR create_card_token.")
+      }),
+      execute: async ({ customer_id, card_token }) => {
+        return client.createCustomerCard(customer_id, card_token);
+      }
+    }),
+    get_customer_card: ai.tool({
+      description: desc("get_customer_card"),
+      inputSchema: zod.z.object({
+        customer_id: zod.z.string(),
+        card_id: zod.z.string()
+      }),
+      execute: async ({ customer_id, card_id }) => {
+        return client.getCustomerCard(customer_id, card_id);
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.7 — Subscription / Plan / Refund / Preference extensions
+    // ─────────────────────────────────────────────────────────────────────────
+    get_subscription_plan: ai.tool({
+      description: desc("get_subscription_plan"),
+      inputSchema: zod.z.object({ plan_id: zod.z.string() }),
+      execute: async ({ plan_id }) => {
+        return client.getSubscriptionPlan(plan_id);
+      }
+    }),
+    update_subscription: ai.tool({
+      description: desc("update_subscription"),
+      inputSchema: zod.z.object({
+        subscription_id: zod.z.string(),
+        transaction_amount: zod.z.number().positive().optional(),
+        card_token_id: zod.z.string().optional(),
+        status: zod.z.enum(["authorized", "paused", "cancelled"]).optional(),
+        reason: zod.z.string().optional(),
+        external_reference: zod.z.string().optional()
+      }),
+      execute: async ({ subscription_id, ...patch }) => {
+        const cleaned = {};
+        for (const [k, v] of Object.entries(patch)) {
+          if (v !== void 0) cleaned[k] = v;
+        }
+        return client.updatePreapproval(subscription_id, cleaned);
+      }
+    }),
+    search_subscriptions: ai.tool({
+      description: desc("search_subscriptions"),
+      inputSchema: zod.z.object({
+        status: zod.z.string().optional(),
+        payer_email: zod.z.string().email().optional(),
+        external_reference: zod.z.string().optional(),
+        plan_id: zod.z.string().optional(),
+        limit: zod.z.number().int().min(1).max(100).optional(),
+        offset: zod.z.number().int().min(0).optional()
+      }),
+      execute: async ({ status, payer_email, external_reference, plan_id, limit, offset }) => {
+        const params = {};
+        if (status !== void 0) params.status = status;
+        if (payer_email !== void 0) params.payerEmail = payer_email;
+        if (external_reference !== void 0) params.externalReference = external_reference;
+        if (plan_id !== void 0) params.preapproval_plan_id = plan_id;
+        if (limit !== void 0) params.limit = limit;
+        if (offset !== void 0) params.offset = offset;
+        return client.searchPreapprovals(params);
+      }
+    }),
+    get_refund: ai.tool({
+      description: desc("get_refund"),
+      inputSchema: zod.z.object({
+        payment_id: zod.z.string(),
+        refund_id: zod.z.string()
+      }),
+      execute: async ({ payment_id, refund_id }) => {
+        return client.getRefund(payment_id, refund_id);
+      }
+    }),
+    update_payment_preference: ai.tool({
+      description: desc("update_payment_preference"),
+      inputSchema: zod.z.object({
+        preference_id: zod.z.string(),
+        notification_url: zod.z.string().url().optional(),
+        external_reference: zod.z.string().optional(),
+        statement_descriptor: zod.z.string().optional()
+      }),
+      execute: async ({ preference_id, ...patch }) => {
+        const cleaned = {};
+        for (const [k, v] of Object.entries(patch)) {
+          if (v !== void 0) cleaned[k] = v;
+        }
+        return client.updatePreference(preference_id, cleaned);
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.7 — Merchant Orders
+    // ─────────────────────────────────────────────────────────────────────────
+    get_merchant_order: ai.tool({
+      description: desc("get_merchant_order"),
+      inputSchema: zod.z.object({ merchant_order_id: zod.z.string() }),
+      execute: async ({ merchant_order_id }) => {
+        return client.getMerchantOrder(merchant_order_id);
+      }
+    }),
+    search_merchant_orders: ai.tool({
+      description: desc("search_merchant_orders"),
+      inputSchema: zod.z.object({
+        preference_id: zod.z.string().optional(),
+        external_reference: zod.z.string().optional(),
+        status: zod.z.string().optional(),
+        limit: zod.z.number().int().min(1).max(100).optional(),
+        offset: zod.z.number().int().min(0).optional()
+      }),
+      execute: async ({ preference_id, external_reference, status, limit, offset }) => {
+        const params = {};
+        if (preference_id !== void 0) params.preferenceId = preference_id;
+        if (external_reference !== void 0) params.externalReference = external_reference;
+        if (status !== void 0) params.status = status;
+        if (limit !== void 0) params.limit = limit;
+        if (offset !== void 0) params.offset = offset;
+        return client.searchMerchantOrders(params);
+      }
+    }),
+    update_merchant_order: ai.tool({
+      description: desc("update_merchant_order"),
+      inputSchema: zod.z.object({
+        merchant_order_id: zod.z.string(),
+        patch: zod.z.record(zod.z.string(), zod.z.unknown())
+      }),
+      execute: async ({ merchant_order_id, patch }) => {
+        return client.updateMerchantOrder(merchant_order_id, patch);
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.7 — Stores + POS CRUD completion
+    // ─────────────────────────────────────────────────────────────────────────
+    get_store: ai.tool({
+      description: desc("get_store"),
+      inputSchema: zod.z.object({
+        user_id: zod.z.string(),
+        store_id: zod.z.string()
+      }),
+      execute: async ({ user_id, store_id }) => {
+        return client.getStore(user_id, store_id);
+      }
+    }),
+    update_store: ai.tool({
+      description: desc("update_store"),
+      inputSchema: zod.z.object({
+        user_id: zod.z.string(),
+        store_id: zod.z.string(),
+        name: zod.z.string().optional(),
+        external_id: zod.z.string().optional()
+      }),
+      execute: async ({ user_id, store_id, ...patch }) => {
+        const cleaned = {};
+        for (const [k, v] of Object.entries(patch)) {
+          if (v !== void 0) cleaned[k] = v;
+        }
+        return client.updateStore(user_id, store_id, cleaned);
+      }
+    }),
+    delete_store: ai.tool({
+      description: desc("delete_store"),
+      inputSchema: zod.z.object({
+        user_id: zod.z.string(),
+        store_id: zod.z.string()
+      }),
+      execute: async ({ user_id, store_id }) => {
+        await client.deleteStore(user_id, store_id);
+        return { user_id, store_id, deleted: true };
+      }
+    }),
+    get_pos: ai.tool({
+      description: desc("get_pos"),
+      inputSchema: zod.z.object({ pos_id: zod.z.string() }),
+      execute: async ({ pos_id }) => {
+        return client.getPos(pos_id);
+      }
+    }),
+    update_pos: ai.tool({
+      description: desc("update_pos"),
+      inputSchema: zod.z.object({
+        pos_id: zod.z.string(),
+        name: zod.z.string().optional(),
+        external_id: zod.z.string().optional(),
+        category: zod.z.number().optional()
+      }),
+      execute: async ({ pos_id, ...patch }) => {
+        const cleaned = {};
+        for (const [k, v] of Object.entries(patch)) {
+          if (v !== void 0) cleaned[k] = v;
+        }
+        return client.updatePos(pos_id, cleaned);
+      }
+    }),
+    delete_pos: ai.tool({
+      description: desc("delete_pos"),
+      inputSchema: zod.z.object({ pos_id: zod.z.string() }),
+      execute: async ({ pos_id }) => {
+        await client.deletePos(pos_id);
+        return { pos_id, deleted: true };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.7 — Bank Accounts
+    // ─────────────────────────────────────────────────────────────────────────
+    list_bank_accounts: ai.tool({
+      description: desc("list_bank_accounts"),
+      inputSchema: zod.z.object({}),
+      execute: async () => {
+        const accounts = await client.listBankAccounts();
+        return { accounts };
+      }
+    }),
+    register_bank_account: ai.tool({
+      description: desc("register_bank_account"),
+      inputSchema: zod.z.object({
+        cbu: zod.z.string().regex(/^\d{22}$/),
+        alias: zod.z.string().optional()
+      }),
+      execute: async (input) => {
+        const params = {
+          cbu: input.cbu
+        };
+        if (input.alias !== void 0) params.alias = input.alias;
+        return client.registerBankAccount(params);
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.7 — Point Devices físicos
+    // ─────────────────────────────────────────────────────────────────────────
+    list_point_devices: ai.tool({
+      description: desc("list_point_devices"),
+      inputSchema: zod.z.object({
+        pos_id: zod.z.union([zod.z.string(), zod.z.number()]).optional(),
+        limit: zod.z.number().int().min(1).max(100).optional(),
+        offset: zod.z.number().int().min(0).optional()
+      }),
+      execute: async ({ pos_id, limit, offset }) => {
+        const params = {};
+        if (pos_id !== void 0) params.posId = pos_id;
+        if (limit !== void 0) params.limit = limit;
+        if (offset !== void 0) params.offset = offset;
+        return client.listPointDevices(params);
+      }
+    }),
+    update_point_device_mode: ai.tool({
+      description: desc("update_point_device_mode"),
+      inputSchema: zod.z.object({
+        device_id: zod.z.string(),
+        operating_mode: zod.z.enum(["PDV", "STANDALONE"])
+      }),
+      execute: async ({ device_id, operating_mode }) => {
+        return client.updatePointDeviceOperatingMode(device_id, operating_mode);
+      }
+    }),
+    create_point_payment_intent: ai.tool({
+      description: desc("create_point_payment_intent"),
+      inputSchema: zod.z.object({
+        device_id: zod.z.string(),
+        amount_centavos: zod.z.number().int().positive().describe("Amount in CENTAVOS (NOT pesos). 100 = $1, 1000 = $10, 10000 = $100."),
+        description: zod.z.string().optional(),
+        external_reference: zod.z.string().optional(),
+        installments: zod.z.number().int().min(1).max(24).optional(),
+        installments_cost: zod.z.enum(["seller", "buyer"]).optional(),
+        print_on_terminal: zod.z.boolean().optional(),
+        ticket_number: zod.z.string().optional()
+      }),
+      execute: async (input) => {
+        const params = {
+          amount: input.amount_centavos
+        };
+        if (input.description !== void 0) params.description = input.description;
+        if (input.external_reference !== void 0) params.externalReference = input.external_reference;
+        if (input.installments !== void 0) params.installments = input.installments;
+        if (input.installments_cost !== void 0) params.installmentsCost = input.installments_cost;
+        if (input.print_on_terminal !== void 0) params.printOnTerminal = input.print_on_terminal;
+        if (input.ticket_number !== void 0) params.ticketNumber = input.ticket_number;
+        return client.createPointPaymentIntent(input.device_id, params);
+      }
+    }),
+    get_point_payment_intent: ai.tool({
+      description: desc("get_point_payment_intent"),
+      inputSchema: zod.z.object({ intent_id: zod.z.string() }),
+      execute: async ({ intent_id }) => {
+        return client.getPointPaymentIntent(intent_id);
+      }
+    }),
+    cancel_point_payment_intent: ai.tool({
+      description: desc("cancel_point_payment_intent"),
+      inputSchema: zod.z.object({
+        device_id: zod.z.string(),
+        intent_id: zod.z.string()
+      }),
+      execute: async ({ device_id, intent_id }) => {
+        return client.cancelPointPaymentIntent(device_id, intent_id);
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.7 — Pure helpers
+    // ─────────────────────────────────────────────────────────────────────────
+    compute_marketplace_fee: ai.tool({
+      description: desc("compute_marketplace_fee"),
+      inputSchema: zod.z.object({
+        amount_ars: zod.z.number().positive(),
+        flat_ars: zod.z.number().nonnegative().optional(),
+        percent: zod.z.number().min(0).max(100).optional(),
+        min_ars: zod.z.number().nonnegative().optional(),
+        max_ars: zod.z.number().nonnegative().optional(),
+        round: zod.z.boolean().optional()
+      }),
+      execute: async (input) => {
+        const rule = {};
+        if (input.flat_ars !== void 0) rule.flatArs = input.flat_ars;
+        if (input.percent !== void 0) rule.percent = input.percent;
+        if (input.min_ars !== void 0) rule.minArs = input.min_ars;
+        if (input.max_ars !== void 0) rule.maxArs = input.max_ars;
+        if (input.round !== void 0) rule.round = input.round;
+        const fee = computeMarketplaceFee(input.amount_ars, rule);
+        return {
+          amount_ars: input.amount_ars,
+          marketplace_fee: fee,
+          seller_receives: input.amount_ars - fee,
+          rule_applied: rule
+        };
+      }
+    }),
+    explain_payment_status: ai.tool({
+      description: desc("explain_payment_status"),
+      inputSchema: zod.z.object({
+        payment_id: zod.z.string().optional().describe("If provided, fetches the Payment first."),
+        payment: zod.z.record(zod.z.string(), zod.z.unknown()).optional().describe("Alternatively, pass a Payment object directly (saves a network round-trip).")
+      }),
+      execute: async ({ payment_id, payment }) => {
+        let p;
+        if (payment) {
+          p = payment;
+        } else if (payment_id) {
+          p = await client.getPayment(payment_id);
+        } else {
+          return {
+            ok: false,
+            error: "Pass either payment_id or payment."
+          };
+        }
+        const explanation = explainPaymentStatus(p);
+        return {
+          ok: true,
+          payment_status: p.status,
+          payment_status_detail: p.status_detail ?? null,
+          ...explanation
+        };
+      }
     })
   };
 }
@@ -2817,10 +4065,16 @@ exports.MercadoPagoPaymentRejectedError = MercadoPagoPaymentRejectedError;
 exports.MercadoPagoRateLimitError = MercadoPagoRateLimitError;
 exports.MercadoPagoSelfPaymentError = MercadoPagoSelfPaymentError;
 exports.MercadoPagoTimeoutError = MercadoPagoTimeoutError;
+exports.TEST_CARDS_AR = TEST_CARDS_AR;
+exports.TEST_PAYERS_AR = TEST_PAYERS_AR;
+exports.analyze3DS = analyze3DS;
 exports.buildAuthorizeUrl = buildAuthorizeUrl;
+exports.buildTestCardScenario = buildTestCardScenario;
 exports.classifyError = classifyError;
+exports.computeMarketplaceFee = computeMarketplaceFee;
 exports.exchangeCodeForToken = exchangeCodeForToken;
 exports.expirationTimeMs = expirationTimeMs;
+exports.explainPaymentStatus = explainPaymentStatus;
 exports.isExpiringSoon = isExpiringSoon;
 exports.mercadoPagoTools = mercadoPagoTools;
 exports.parseWebhookEvent = parseWebhookEvent;