@ar-agents/mercadopago 0.6.0 → 0.7.0

package/dist/index.js

@@ -1023,6 +1023,215 @@ var MercadoPagoClient = class {
   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 };
+  }
 };
 z.enum(["MLA", "MLB", "MLM", "MCO", "MLC", "MLU"]);
 var CurrencyIdSchema = z.enum(["ARS", "USD", "BRL", "MXN"]);
@@ -1403,6 +1612,63 @@ z.object({
     bank_name: z.string().optional()
   }).passthrough().optional()
 }).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  status: z.string().optional(),
+  external_reference: z.string().nullable().optional(),
+  preference_id: z.union([z.string(), z.number()]).optional(),
+  payments: z.array(z.unknown()).optional(),
+  shipments: z.array(z.unknown()).optional(),
+  payer: z.unknown().optional(),
+  collector: z.unknown().optional(),
+  marketplace: z.string().optional(),
+  total_amount: z.number().optional(),
+  paid_amount: z.number().optional(),
+  refunded_amount: z.number().optional(),
+  shipping_cost: z.number().optional(),
+  date_created: z.string().optional(),
+  last_updated: z.string().optional(),
+  site_id: z.string().optional(),
+  order_status: z.string().optional()
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  cbu: z.string().optional(),
+  alias: z.string().nullable().optional(),
+  bank_name: z.string().optional(),
+  account_type: z.string().optional(),
+  status: z.string().optional(),
+  is_default: z.boolean().optional(),
+  date_created: z.string().optional()
+}).passthrough();
+z.object({
+  id: z.string(),
+  pos_id: z.union([z.string(), z.number()]).nullable().optional(),
+  store_id: z.union([z.string(), z.number()]).nullable().optional(),
+  external_pos_id: z.string().nullable().optional(),
+  operating_mode: z.union([z.literal("PDV"), z.literal("STANDALONE"), z.string()]).optional()
+}).passthrough();
+z.object({
+  id: z.string(),
+  device_id: z.string().optional(),
+  amount: z.number().optional(),
+  state: z.union([
+    z.literal("OPEN"),
+    z.literal("PROCESSING"),
+    z.literal("FINISHED"),
+    z.literal("CANCELED"),
+    z.literal("ERROR"),
+    z.string()
+  ]).optional(),
+  payment: z.object({
+    id: z.union([z.string(), z.number()]).optional(),
+    type: z.string().optional(),
+    installments: z.number().optional(),
+    installments_cost: z.string().optional(),
+    print_on_terminal: z.boolean().optional()
+  }).passthrough().optional(),
+  additional_info: z.unknown().optional()
+}).passthrough();
 
 // src/oauth.ts
 var DEFAULT_AUTHORIZE_URL = "https://auth.mercadopago.com.ar/authorization";
@@ -1470,6 +1736,243 @@ 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: {
@@ -1707,7 +2210,41 @@ var DEFAULT_DESCRIPTIONS = {
   // ── 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."
+  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];
@@ -3101,6 +3638,396 @@ function mercadoPagoTools(client, options) {
           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: tool({
+      description: desc("get_customer"),
+      inputSchema: z.object({ customer_id: z.string() }),
+      execute: async ({ customer_id }) => {
+        return client.getCustomer(customer_id);
+      }
+    }),
+    update_customer: tool({
+      description: desc("update_customer"),
+      inputSchema: z.object({
+        customer_id: z.string(),
+        first_name: z.string().optional(),
+        last_name: z.string().optional(),
+        phone: z.object({ area_code: z.string().optional(), number: z.string().optional() }).optional(),
+        identification: z.object({ type: z.string(), number: z.string() }).optional(),
+        address: z.object({
+          street_name: z.string().optional(),
+          street_number: z.number().optional(),
+          zip_code: z.string().optional()
+        }).optional(),
+        description: z.string().optional(),
+        default_card: 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: tool({
+      description: desc("create_customer_card"),
+      inputSchema: z.object({
+        customer_id: z.string(),
+        card_token: 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: tool({
+      description: desc("get_customer_card"),
+      inputSchema: z.object({
+        customer_id: z.string(),
+        card_id: 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: tool({
+      description: desc("get_subscription_plan"),
+      inputSchema: z.object({ plan_id: z.string() }),
+      execute: async ({ plan_id }) => {
+        return client.getSubscriptionPlan(plan_id);
+      }
+    }),
+    update_subscription: tool({
+      description: desc("update_subscription"),
+      inputSchema: z.object({
+        subscription_id: z.string(),
+        transaction_amount: z.number().positive().optional(),
+        card_token_id: z.string().optional(),
+        status: z.enum(["authorized", "paused", "cancelled"]).optional(),
+        reason: z.string().optional(),
+        external_reference: 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: tool({
+      description: desc("search_subscriptions"),
+      inputSchema: z.object({
+        status: z.string().optional(),
+        payer_email: z.string().email().optional(),
+        external_reference: z.string().optional(),
+        plan_id: z.string().optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+        offset: 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: tool({
+      description: desc("get_refund"),
+      inputSchema: z.object({
+        payment_id: z.string(),
+        refund_id: z.string()
+      }),
+      execute: async ({ payment_id, refund_id }) => {
+        return client.getRefund(payment_id, refund_id);
+      }
+    }),
+    update_payment_preference: tool({
+      description: desc("update_payment_preference"),
+      inputSchema: z.object({
+        preference_id: z.string(),
+        notification_url: z.string().url().optional(),
+        external_reference: z.string().optional(),
+        statement_descriptor: 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: tool({
+      description: desc("get_merchant_order"),
+      inputSchema: z.object({ merchant_order_id: z.string() }),
+      execute: async ({ merchant_order_id }) => {
+        return client.getMerchantOrder(merchant_order_id);
+      }
+    }),
+    search_merchant_orders: tool({
+      description: desc("search_merchant_orders"),
+      inputSchema: z.object({
+        preference_id: z.string().optional(),
+        external_reference: z.string().optional(),
+        status: z.string().optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+        offset: 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: tool({
+      description: desc("update_merchant_order"),
+      inputSchema: z.object({
+        merchant_order_id: z.string(),
+        patch: z.record(z.string(), z.unknown())
+      }),
+      execute: async ({ merchant_order_id, patch }) => {
+        return client.updateMerchantOrder(merchant_order_id, patch);
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.7 — Stores + POS CRUD completion
+    // ─────────────────────────────────────────────────────────────────────────
+    get_store: tool({
+      description: desc("get_store"),
+      inputSchema: z.object({
+        user_id: z.string(),
+        store_id: z.string()
+      }),
+      execute: async ({ user_id, store_id }) => {
+        return client.getStore(user_id, store_id);
+      }
+    }),
+    update_store: tool({
+      description: desc("update_store"),
+      inputSchema: z.object({
+        user_id: z.string(),
+        store_id: z.string(),
+        name: z.string().optional(),
+        external_id: 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: tool({
+      description: desc("delete_store"),
+      inputSchema: z.object({
+        user_id: z.string(),
+        store_id: z.string()
+      }),
+      execute: async ({ user_id, store_id }) => {
+        await client.deleteStore(user_id, store_id);
+        return { user_id, store_id, deleted: true };
+      }
+    }),
+    get_pos: tool({
+      description: desc("get_pos"),
+      inputSchema: z.object({ pos_id: z.string() }),
+      execute: async ({ pos_id }) => {
+        return client.getPos(pos_id);
+      }
+    }),
+    update_pos: tool({
+      description: desc("update_pos"),
+      inputSchema: z.object({
+        pos_id: z.string(),
+        name: z.string().optional(),
+        external_id: z.string().optional(),
+        category: 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: tool({
+      description: desc("delete_pos"),
+      inputSchema: z.object({ pos_id: z.string() }),
+      execute: async ({ pos_id }) => {
+        await client.deletePos(pos_id);
+        return { pos_id, deleted: true };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.7 — Bank Accounts
+    // ─────────────────────────────────────────────────────────────────────────
+    list_bank_accounts: tool({
+      description: desc("list_bank_accounts"),
+      inputSchema: z.object({}),
+      execute: async () => {
+        const accounts = await client.listBankAccounts();
+        return { accounts };
+      }
+    }),
+    register_bank_account: tool({
+      description: desc("register_bank_account"),
+      inputSchema: z.object({
+        cbu: z.string().regex(/^\d{22}$/),
+        alias: 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: tool({
+      description: desc("list_point_devices"),
+      inputSchema: z.object({
+        pos_id: z.union([z.string(), z.number()]).optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+        offset: 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: tool({
+      description: desc("update_point_device_mode"),
+      inputSchema: z.object({
+        device_id: z.string(),
+        operating_mode: z.enum(["PDV", "STANDALONE"])
+      }),
+      execute: async ({ device_id, operating_mode }) => {
+        return client.updatePointDeviceOperatingMode(device_id, operating_mode);
+      }
+    }),
+    create_point_payment_intent: tool({
+      description: desc("create_point_payment_intent"),
+      inputSchema: z.object({
+        device_id: z.string(),
+        amount_centavos: z.number().int().positive().describe("Amount in CENTAVOS (NOT pesos). 100 = $1, 1000 = $10, 10000 = $100."),
+        description: z.string().optional(),
+        external_reference: z.string().optional(),
+        installments: z.number().int().min(1).max(24).optional(),
+        installments_cost: z.enum(["seller", "buyer"]).optional(),
+        print_on_terminal: z.boolean().optional(),
+        ticket_number: 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: tool({
+      description: desc("get_point_payment_intent"),
+      inputSchema: z.object({ intent_id: z.string() }),
+      execute: async ({ intent_id }) => {
+        return client.getPointPaymentIntent(intent_id);
+      }
+    }),
+    cancel_point_payment_intent: tool({
+      description: desc("cancel_point_payment_intent"),
+      inputSchema: z.object({
+        device_id: z.string(),
+        intent_id: z.string()
+      }),
+      execute: async ({ device_id, intent_id }) => {
+        return client.cancelPointPaymentIntent(device_id, intent_id);
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.7 — Pure helpers
+    // ─────────────────────────────────────────────────────────────────────────
+    compute_marketplace_fee: tool({
+      description: desc("compute_marketplace_fee"),
+      inputSchema: z.object({
+        amount_ars: z.number().positive(),
+        flat_ars: z.number().nonnegative().optional(),
+        percent: z.number().min(0).max(100).optional(),
+        min_ars: z.number().nonnegative().optional(),
+        max_ars: z.number().nonnegative().optional(),
+        round: 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: tool({
+      description: desc("explain_payment_status"),
+      inputSchema: z.object({
+        payment_id: z.string().optional().describe("If provided, fetches the Payment first."),
+        payment: z.record(z.string(), 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
+        };
+      }
     })
   };
 }
@@ -3124,6 +4051,6 @@ var InMemoryStateAdapter = class {
   }
 };
 
-export { InMemoryStateAdapter, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, TEST_CARDS_AR, TEST_PAYERS_AR, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, exchangeCodeForToken, expirationTimeMs, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
+export { InMemoryStateAdapter, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, TEST_CARDS_AR, TEST_PAYERS_AR, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, computeMarketplaceFee, exchangeCodeForToken, expirationTimeMs, explainPaymentStatus, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map