@ar-agents/mercadopago 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- MP v0.6: account/balance + settlements + 3DS analyzer + test cards. **+6 tools (56 total)**.
+
+  **Account / Balance / Settlements (4 tools)**:
+
+  - `get_account_balance` — current MP wallet `{ available, unavailable, total, currency_id }`. Per-seller in marketplace setups.
+  - `list_account_movements({ from?, to?, limit?, offset? })` — wallet movement log (incoming payments, refunds, holdings, transfers).
+  - `list_settlements({ from?, to?, status? })` — `release_money` transfers from MP wallet → registered CBU.
+  - `get_settlement(id)` — single settlement detail with bank_account info.
+
+  **3DS analyzer (1 tool + 1 helper)**:
+
+  - `analyze_payment_3ds(payment_id)` — fetches the Payment, derives `{ status: 'not_required'|'frictionless'|'challenge_required'|'rejected'|'unknown', mode, challengeUrl, description }`. When `challengeUrl !== null`, MUST redirect the buyer to complete authentication.
+  - `analyze3DS(payment)` exported as a pure helper for callers who already have a Payment object.
+
+  **Test cards (1 tool + helpers)**:
+
+  - `get_test_cards` — returns the official AR (MLA) sandbox cards: VISA/Mastercard/Amex credit + debit. Each has the "magic" holder names that route to specific status_detail (APRO, OTHE, CONT, FUND, CALL, SECU, EXPI, FORM).
+  - `TEST_CARDS_AR`, `TEST_PAYERS_AR`, `buildTestCardScenario(card, scenario, amount)` exported for direct use in test files.
+
+  **132 tests pass** (was 117; +15 v0.6 tests). publint clean. attw 🟢. 24.3 KB brotli'd (within 32 KB budget).
+
 ## 0.5.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -960,6 +960,71 @@ 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}`);
+  }
 };
 zod.z.enum(["MLA", "MLB", "MLM", "MCO", "MLC", "MLU"]);
 var CurrencyIdSchema = zod.z.enum(["ARS", "USD", "BRL", "MXN"]);
@@ -1308,6 +1373,38 @@ 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();
 
 // src/oauth.ts
 var DEFAULT_AUTHORIZE_URL = "https://auth.mercadopago.com.ar/authorization";
@@ -1374,6 +1471,134 @@ function expirationTimeMs(issuedAtMs, expiresInSeconds) {
 function isExpiringSoon(expirationMs, skewSeconds = 300) {
   return Date.now() + skewSeconds * 1e3 >= expirationMs;
 }
+
+// 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 +1700,16 @@ 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."
 };
 function mercadoPagoTools(client, options) {
   const desc = (name) => options.descriptions?.[name] ?? DEFAULT_DESCRIPTIONS[name];
@@ -2782,6 +3016,93 @@ 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."
+        };
+      }
     })
   };
 }
@@ -2817,7 +3138,11 @@ 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.exchangeCodeForToken = exchangeCodeForToken;
 exports.expirationTimeMs = expirationTimeMs;