@ar-agents/mercadopago 0.3.0 → 0.5.0

package/dist/index.js

@@ -505,6 +505,9 @@ var MercadoPagoClient = class {
     if (params.expires !== void 0) body.expires = params.expires;
     if (params.expirationDateFrom) body.expiration_date_from = params.expirationDateFrom;
     if (params.expirationDateTo) body.expiration_date_to = params.expirationDateTo;
+    if (params.marketplace) body.marketplace = params.marketplace;
+    if (params.marketplaceFee !== void 0) body.marketplace_fee = params.marketplaceFee;
+    if (params.collectorId !== void 0) body.collector_id = params.collectorId;
     return this.request("POST", "/checkout/preferences", body);
   }
   async getPreference(id) {
@@ -712,7 +715,693 @@ var MercadoPagoClient = class {
       `/instore/orders/qr/seller/collectors/${encodeURIComponent(userId)}/pos/${encodeURIComponent(externalPosId)}/qrs`
     );
   }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Subscription Plans (preapproval_plan — reusable plans, v0.4)
+  // ───────────────────────────────────────────────────────────────────────────
+  /**
+   * Create a reusable subscription plan. Customers later subscribe to it via
+   * `subscribeToPlan` (which creates a preapproval pointing at the plan).
+   *
+   * Use this when you have fixed tiers (Básico/Pro/Enterprise). For custom
+   * per-customer amounts, skip plans and use `createPreapproval` directly.
+   */
+  async createSubscriptionPlan(params) {
+    const body = {
+      reason: params.reason,
+      back_url: params.backUrl,
+      auto_recurring: {
+        frequency: params.frequency,
+        frequency_type: params.frequencyType,
+        transaction_amount: params.amount,
+        currency_id: params.currency,
+        ...params.freeTrialFrequency !== void 0 && params.freeTrialFrequencyType !== void 0 ? {
+          free_trial: {
+            frequency: params.freeTrialFrequency,
+            frequency_type: params.freeTrialFrequencyType
+          }
+        } : {}
+      }
+    };
+    if (params.externalReference) body.external_reference = params.externalReference;
+    return this.request("POST", "/preapproval_plan", body);
+  }
+  async getSubscriptionPlan(id) {
+    return this.request("GET", `/preapproval_plan/${id}`);
+  }
+  async listSubscriptionPlans(params = {}) {
+    const query = {
+      limit: params.limit ?? 30,
+      offset: params.offset ?? 0
+    };
+    if (params.status) query["status"] = params.status;
+    return this.request("GET", "/preapproval_plan/search", void 0, { query });
+  }
+  async updateSubscriptionPlan(id, patch) {
+    const body = {};
+    if (patch.reason !== void 0) body.reason = patch.reason;
+    if (patch.status !== void 0) body.status = patch.status;
+    if (patch.backUrl !== void 0) body.back_url = patch.backUrl;
+    if (patch.amount !== void 0) {
+      body.auto_recurring = { transaction_amount: patch.amount };
+    }
+    return this.request("PUT", `/preapproval_plan/${id}`, body);
+  }
+  /**
+   * Subscribe a customer to an existing plan. Returns a Preapproval with
+   * `init_point` URL where the buyer completes the first payment.
+   */
+  async subscribeToPlan(params) {
+    const body = {
+      preapproval_plan_id: params.planId,
+      payer_email: params.payerEmail
+    };
+    if (params.cardTokenId) body.card_token_id = params.cardTokenId;
+    if (params.externalReference) body.external_reference = params.externalReference;
+    return this.request("POST", "/preapproval", body, {
+      classifyContext: { payerEmail: params.payerEmail }
+    });
+  }
+  /**
+   * List the auto-charge attempts (authorized_payments) under a preapproval.
+   * Useful for "show me the cobros of the last 6 months for this client".
+   */
+  async listSubscriptionPayments(preapprovalId, params = {}) {
+    const query = {
+      preapproval_id: preapprovalId,
+      limit: params.limit ?? 30,
+      offset: params.offset ?? 0
+    };
+    return this.request(
+      "GET",
+      `/authorized_payments/search`,
+      void 0,
+      { query, classifyContext: { preapprovalId } }
+    );
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Stores + POS (for QR payments self-serve setup, v0.4)
+  // ───────────────────────────────────────────────────────────────────────────
+  /** Create a store for the seller. POSes (for QR) live under stores. */
+  async createStore(userId, params) {
+    const body = {
+      name: params.name,
+      external_id: params.externalId
+    };
+    if (params.location) {
+      body.location = {
+        ...params.location.addressLine ? { address_line: params.location.addressLine } : {},
+        ...params.location.cityName ? { city_name: params.location.cityName } : {},
+        ...params.location.stateName ? { state_name: params.location.stateName } : {},
+        ...params.location.countryId ? { country_id: params.location.countryId } : {},
+        ...params.location.latitude !== void 0 ? { latitude: params.location.latitude } : {},
+        ...params.location.longitude !== void 0 ? { longitude: params.location.longitude } : {}
+      };
+    }
+    return this.request("POST", `/users/${encodeURIComponent(userId)}/stores`, body);
+  }
+  async listStores(userId, params = {}) {
+    const query = {
+      limit: params.limit ?? 50,
+      offset: params.offset ?? 0
+    };
+    return this.request("GET", `/users/${encodeURIComponent(userId)}/stores/search`, void 0, { query });
+  }
+  /** Create a POS under a store. The POS's `external_id` is what `createQrPayment` uses. */
+  async createPos(params) {
+    const body = {
+      name: params.name,
+      external_id: params.externalId,
+      store_id: params.storeId,
+      category: params.category ?? 621102
+      // "Other Food and Beverage Services" — generic default
+    };
+    if (params.fixedAmount !== void 0) body.fixed_amount = params.fixedAmount;
+    return this.request("POST", "/pos", body);
+  }
+  async listPos(params = {}) {
+    const query = {
+      limit: params.limit ?? 50,
+      offset: params.offset ?? 0
+    };
+    if (params.storeId !== void 0) query["store_id"] = String(params.storeId);
+    return this.request("GET", "/pos", void 0, { query });
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Disputes (read-only, v0.4)
+  // ───────────────────────────────────────────────────────────────────────────
+  async listPaymentDisputes(paymentId) {
+    return this.request("GET", `/v1/payments/${paymentId}/disputes`, void 0, {
+      classifyContext: { paymentId }
+    });
+  }
+  async getDispute(paymentId, disputeId) {
+    return this.request(
+      "GET",
+      `/v1/payments/${paymentId}/disputes/${disputeId}`,
+      void 0,
+      { classifyContext: { paymentId } }
+    );
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Identification Types + Issuers (lookup helpers, v0.4)
+  // ───────────────────────────────────────────────────────────────────────────
+  /** List valid identification types for the seller's site. AR returns DNI/CI/LE/LC/Otro/Pasaporte/CUIT/CUIL. */
+  async listIdentificationTypes() {
+    return this.request("GET", "/v1/identification_types");
+  }
+  /** List card issuers for a payment method. Useful with `bin` for installments. */
+  async listIssuers(params) {
+    const query = {
+      payment_method_id: params.paymentMethodId
+    };
+    if (params.bin) query["bin"] = params.bin;
+    return this.request("GET", "/v1/payment_methods/card_issuers", void 0, { query });
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Webhooks management (v0.4)
+  // ───────────────────────────────────────────────────────────────────────────
+  /** List configured webhook subscriptions. */
+  async listWebhooks() {
+    return this.request("GET", "/v1/webhooks");
+  }
+  /** Create a webhook subscription for a topic. */
+  async createWebhook(params) {
+    return this.request("POST", "/v1/webhooks", {
+      url: params.url,
+      topic: params.topic
+    });
+  }
+  async updateWebhook(id, patch) {
+    return this.request("PUT", `/v1/webhooks/${id}`, patch);
+  }
+  async deleteWebhook(id) {
+    await this.request("DELETE", `/v1/webhooks/${id}`);
+  }
+  // ──────────────────────────────────────────────────────────────────────────
+  // v0.5 — Order Management API
+  //
+  // The Order API is MP's newer abstraction for purchases, replacing some
+  // Preference flows. Distinct from Preference: Order is a transactional
+  // entity with explicit lifecycle (created → processed → captured/canceled),
+  // supports manual capture (auth-only, capture later), and can attach
+  // multiple payments to a single Order.
+  //
+  // Use Order when you need:
+  // - Auth-only flow (capture later, e.g. ride-share, hotels)
+  // - Multi-payment aggregation (one Order = N partial payments)
+  // - In-store + online unified status
+  //
+  // Stick with Preference (Checkout Pro) when you just need a hosted pay-link.
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * Create a new Order. Use `capture_mode: "manual"` for auth-only flows
+   * where you want to capture funds later (ride-share, hotels, marketplaces).
+   *
+   * For marketplace splits, set `marketplace`, `marketplace_fee`,
+   * `collector_id` — see `MarketplaceParams`.
+   */
+  async createOrder(params, options) {
+    const body = {
+      type: params.type
+    };
+    if (params.currency_id) body.currency_id = params.currency_id;
+    if (params.external_reference) body.external_reference = params.external_reference;
+    if (params.items) body.items = params.items;
+    if (params.total_amount !== void 0) body.total_amount = params.total_amount;
+    if (params.payer) body.payer = params.payer;
+    if (params.capture_mode) body.capture_mode = params.capture_mode;
+    if (params.notification_url) body.notification_url = params.notification_url;
+    if (params.marketplace) body.marketplace = params.marketplace;
+    if (params.marketplace_fee !== void 0) body.marketplace_fee = params.marketplace_fee;
+    if (params.collector_id !== void 0) body.collector_id = params.collector_id;
+    return this.request("POST", "/v1/orders", body, options);
+  }
+  async getOrder(id) {
+    return this.request("GET", `/v1/orders/${id}`);
+  }
+  async updateOrder(id, patch) {
+    return this.request("PUT", `/v1/orders/${id}`, patch);
+  }
+  /**
+   * 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.
+   */
+  async captureOrder(id, amount) {
+    const body = amount !== void 0 ? { amount } : {};
+    return this.request("POST", `/v1/orders/${id}/capture`, body);
+  }
+  /**
+   * Cancel an Order. Releases any auth-holds; marks the Order as canceled.
+   * For orders that have already been captured, use `createRefund` instead.
+   */
+  async cancelOrder(id) {
+    return this.request("POST", `/v1/orders/${id}/cancel`);
+  }
 };
+z.enum(["MLA", "MLB", "MLM", "MCO", "MLC", "MLU"]);
+var CurrencyIdSchema = z.enum(["ARS", "USD", "BRL", "MXN"]);
+var FrequencyTypeSchema = z.enum(["months", "days"]);
+var PreapprovalStatusSchema = z.union([
+  z.literal("pending"),
+  z.literal("authorized"),
+  z.literal("paused"),
+  z.literal("cancelled"),
+  z.string()
+]);
+var AutoRecurringSchema = z.object({
+  frequency: z.number().int().positive(),
+  frequency_type: FrequencyTypeSchema,
+  transaction_amount: z.number().positive(),
+  currency_id: CurrencyIdSchema,
+  start_date: z.string().optional(),
+  end_date: z.string().optional()
+});
+z.object({
+  id: z.string(),
+  status: PreapprovalStatusSchema,
+  payer_email: z.string(),
+  init_point: z.string().url(),
+  external_reference: z.string().optional(),
+  date_created: z.string(),
+  last_modified: z.string(),
+  next_payment_date: z.string().optional(),
+  payer_id: z.union([z.string(), z.number()]).optional(),
+  auto_recurring: AutoRecurringSchema
+});
+var WebhookBodySchema = z.object({
+  type: z.string().optional(),
+  topic: z.string().optional(),
+  action: z.string().optional(),
+  data: z.object({ id: z.union([z.string(), z.number()]) }).optional(),
+  resource: z.string().optional(),
+  user_id: z.union([z.string(), z.number()]).optional(),
+  api_version: z.string().optional(),
+  date_created: z.string().optional(),
+  id: z.union([z.string(), z.number()]).optional(),
+  live_mode: z.boolean().optional()
+}).passthrough();
+var PaymentStatusSchema = z.union([
+  z.literal("pending"),
+  z.literal("approved"),
+  z.literal("authorized"),
+  z.literal("in_process"),
+  z.literal("in_mediation"),
+  z.literal("rejected"),
+  z.literal("cancelled"),
+  z.literal("refunded"),
+  z.literal("charged_back"),
+  z.string()
+]);
+var PaymentSchema = z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  status: PaymentStatusSchema,
+  status_detail: z.string().nullable().optional(),
+  date_created: z.string().nullable().optional(),
+  date_approved: z.string().nullable().optional(),
+  date_last_updated: z.string().nullable().optional(),
+  transaction_amount: z.number(),
+  currency_id: z.string(),
+  installments: z.number().int().nullable().optional(),
+  payment_method_id: z.string().nullable().optional(),
+  payment_type_id: z.string().nullable().optional(),
+  external_reference: z.string().nullable().optional(),
+  description: z.string().nullable().optional(),
+  payer: z.object({
+    id: z.union([z.string(), z.number()]).optional(),
+    email: z.string().nullable().optional(),
+    identification: z.object({
+      type: z.string().nullable().optional(),
+      number: z.string().nullable().optional()
+    }).nullable().optional()
+  }).passthrough().optional(),
+  transaction_details: z.object({
+    net_received_amount: z.number().nullable().optional(),
+    total_paid_amount: z.number().nullable().optional(),
+    installment_amount: z.number().nullable().optional()
+  }).passthrough().optional()
+}).passthrough();
+z.object({
+  paging: z.object({
+    total: z.number(),
+    limit: z.number(),
+    offset: z.number()
+  }),
+  results: z.array(PaymentSchema)
+});
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  payment_id: z.union([z.string(), z.number()]).transform(String),
+  amount: z.number(),
+  source: z.object({
+    id: z.string().nullable().optional(),
+    name: z.string().nullable().optional(),
+    type: z.string().nullable().optional()
+  }).nullable().optional(),
+  date_created: z.string().nullable().optional(),
+  status: z.string().nullable().optional()
+}).passthrough();
+var PreferenceItemSchema = z.object({
+  id: z.string().optional(),
+  title: z.string(),
+  description: z.string().optional(),
+  picture_url: z.string().url().optional(),
+  category_id: z.string().optional(),
+  quantity: z.number().int().positive(),
+  unit_price: z.number().positive(),
+  currency_id: CurrencyIdSchema.optional()
+});
+z.object({
+  id: z.string(),
+  init_point: z.string().url().optional(),
+  sandbox_init_point: z.string().url().optional(),
+  client_id: z.union([z.string(), z.number()]).optional(),
+  collector_id: z.union([z.string(), z.number()]).optional(),
+  items: z.array(PreferenceItemSchema).optional(),
+  external_reference: z.string().nullable().optional(),
+  date_created: z.string().nullable().optional(),
+  expires: z.boolean().optional(),
+  expiration_date_from: z.string().nullable().optional(),
+  expiration_date_to: z.string().nullable().optional()
+}).passthrough();
+z.object({
+  id: z.string(),
+  email: z.string(),
+  first_name: z.string().nullable().optional(),
+  last_name: z.string().nullable().optional(),
+  phone: z.object({ area_code: z.string().nullable().optional(), number: z.string().nullable().optional() }).nullable().optional(),
+  identification: z.object({ type: z.string().nullable().optional(), number: z.string().nullable().optional() }).nullable().optional(),
+  date_created: z.string().nullable().optional(),
+  date_last_updated: z.string().nullable().optional(),
+  description: z.string().nullable().optional()
+}).passthrough();
+z.object({
+  id: z.string(),
+  customer_id: z.string(),
+  expiration_month: z.number().int().nullable().optional(),
+  expiration_year: z.number().int().nullable().optional(),
+  first_six_digits: z.string().nullable().optional(),
+  last_four_digits: z.string().nullable().optional(),
+  payment_method: z.object({
+    id: z.string().nullable().optional(),
+    name: z.string().nullable().optional(),
+    payment_type_id: z.string().nullable().optional()
+  }).nullable().optional(),
+  date_created: z.string().nullable().optional()
+}).passthrough();
+z.object({
+  id: z.string(),
+  name: z.string(),
+  payment_type_id: z.string(),
+  status: z.string(),
+  thumbnail: z.string().nullable().optional(),
+  secure_thumbnail: z.string().nullable().optional(),
+  min_allowed_amount: z.number().nullable().optional(),
+  max_allowed_amount: z.number().nullable().optional()
+}).passthrough();
+z.object({
+  payment_method_id: z.string(),
+  payment_type_id: z.string(),
+  issuer: z.object({
+    id: z.union([z.string(), z.number()]).optional(),
+    name: z.string().nullable().optional()
+  }).nullable().optional(),
+  payer_costs: z.array(
+    z.object({
+      installments: z.number().int(),
+      installment_rate: z.number(),
+      discount_rate: z.number().nullable().optional(),
+      installment_amount: z.number(),
+      total_amount: z.number(),
+      recommended_message: z.string().nullable().optional()
+    }).passthrough()
+  )
+}).passthrough();
+z.object({
+  in_store_order_id: z.string(),
+  qr_data: z.string()
+}).passthrough();
+z.object({
+  id: z.string(),
+  status: z.string().optional(),
+  date_due: z.string().optional(),
+  card_id: z.string().optional(),
+  cardholder: z.unknown().optional()
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  email: z.string().nullable().optional(),
+  nickname: z.string().nullable().optional(),
+  country_id: z.string().nullable().optional(),
+  site_id: z.string().nullable().optional(),
+  user_type: z.string().nullable().optional(),
+  status: z.object({ user_type: z.string().nullable().optional() }).passthrough().nullable().optional()
+}).passthrough();
+z.object({
+  id: z.string(),
+  status: z.string(),
+  reason: z.string(),
+  back_url: z.string().url().optional(),
+  external_reference: z.string().nullable().optional(),
+  date_created: z.string(),
+  last_modified: z.string(),
+  auto_recurring: AutoRecurringSchema
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  name: z.string().optional(),
+  external_id: z.string().optional(),
+  date_creation: z.string().optional(),
+  location: z.object({
+    address_line: z.string().optional(),
+    city_name: z.string().optional(),
+    state_name: z.string().optional(),
+    country_id: z.string().optional(),
+    latitude: z.number().optional(),
+    longitude: z.number().optional()
+  }).passthrough().optional()
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  name: z.string().optional(),
+  external_id: z.string().optional(),
+  store_id: z.union([z.string(), z.number()]).optional(),
+  category: z.number().int().optional(),
+  fixed_amount: z.boolean().optional(),
+  qr: z.object({
+    template_image: z.string().optional(),
+    image: z.string().optional()
+  }).passthrough().optional(),
+  date_creation: z.string().optional()
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  status: z.string(),
+  resource: z.string().optional(),
+  resource_id: z.union([z.string(), z.number()]).optional(),
+  amount: z.number().optional(),
+  date_created: z.string().optional(),
+  reason: z.string().optional(),
+  resolution: z.object({
+    reason: z.string().optional(),
+    result: z.string().optional(),
+    date: z.string().optional()
+  }).passthrough().optional(),
+  /** Documents the buyer / seller submitted as evidence. */
+  documents: z.array(z.unknown()).optional(),
+  /** Buyer's stated complaint. */
+  reason_description: z.string().optional()
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  preapproval_id: z.string().optional(),
+  status: z.string(),
+  payment_id: z.union([z.string(), z.number()]).nullable().optional(),
+  transaction_amount: z.number().optional(),
+  currency_id: z.string().optional(),
+  date_created: z.string().optional(),
+  debit_date: z.string().optional(),
+  next_retry_date: z.string().nullable().optional(),
+  retry_attempt: z.number().optional(),
+  reason: z.string().optional()
+}).passthrough();
+z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.string(),
+  min_length: z.number().optional(),
+  max_length: z.number().optional()
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  name: z.string(),
+  secure_thumbnail: z.string().nullable().optional(),
+  thumbnail: z.string().nullable().optional(),
+  processing_mode: z.string().optional(),
+  status: z.string().optional()
+}).passthrough();
+z.enum([
+  "payment",
+  "subscription_authorized_payment",
+  "subscription_preapproval",
+  "merchant_order",
+  "point_integration_wh",
+  "stop_delivery_op_wh"
+]);
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  url: z.string().url().optional(),
+  status: z.string().optional(),
+  topic: z.string().optional(),
+  date_created: z.string().optional(),
+  date_modified: z.string().optional()
+}).passthrough();
+var OAuthTokenSchema = z.object({
+  access_token: z.string(),
+  token_type: z.string().optional(),
+  /** Seconds until access_token expires. Typically 21600 (6h). */
+  expires_in: z.number().optional(),
+  scope: z.string().optional(),
+  /** The MP user_id of the seller who authorized your app. */
+  user_id: z.union([z.string(), z.number()]).transform(String),
+  refresh_token: z.string().optional(),
+  public_key: z.string().optional(),
+  live_mode: z.boolean().optional()
+}).passthrough();
+var OrderStatusSchema = z.union([
+  z.literal("created"),
+  z.literal("processed"),
+  z.literal("action_required"),
+  z.literal("canceled"),
+  z.literal("expired"),
+  z.literal("refunded"),
+  z.string()
+]);
+var OrderItemSchema = z.object({
+  title: z.string(),
+  unit_price: z.number(),
+  quantity: z.number(),
+  description: z.string().optional(),
+  id: z.string().optional(),
+  category_id: z.string().optional(),
+  picture_url: z.string().optional()
+}).passthrough();
+z.object({
+  id: z.union([z.string(), z.number()]).transform(String),
+  type: z.string().optional(),
+  status: OrderStatusSchema.optional(),
+  status_detail: z.string().optional(),
+  external_reference: z.string().optional(),
+  total_amount: z.union([z.number(), z.string()]).optional(),
+  /** Currency for this Order (e.g. "ARS"). */
+  currency_id: z.string().optional(),
+  date_created: z.string().optional(),
+  date_last_updated: z.string().optional(),
+  items: z.array(OrderItemSchema).optional(),
+  /** Underlying transactions (payments) attached to this Order. */
+  transactions: z.object({
+    payments: z.array(z.unknown()).optional(),
+    refunds: z.array(z.unknown()).optional()
+  }).passthrough().optional(),
+  /** Capture mode: "automatic" (charges immediately) or "manual" (auth-only). */
+  capture_mode: z.string().optional()
+}).passthrough();
+
+// src/oauth.ts
+var DEFAULT_AUTHORIZE_URL = "https://auth.mercadopago.com.ar/authorization";
+var DEFAULT_TOKEN_URL = "https://api.mercadopago.com/oauth/token";
+function buildAuthorizeUrl(params) {
+  const url = new URL(params.authorizeUrl ?? DEFAULT_AUTHORIZE_URL);
+  url.searchParams.set("client_id", params.clientId);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("platform_id", "mp");
+  url.searchParams.set("redirect_uri", params.redirectUri);
+  if (params.state) url.searchParams.set("state", params.state);
+  return url.toString();
+}
+async function exchangeCodeForToken(params) {
+  const url = params.tokenUrl ?? DEFAULT_TOKEN_URL;
+  const fetchFn = params.fetchImpl ?? globalThis.fetch;
+  const res = await fetchFn(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json"
+    },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: params.clientId,
+      client_secret: params.clientSecret,
+      code: params.code,
+      redirect_uri: params.redirectUri
+    }).toString()
+  });
+  return parseTokenResponse(res);
+}
+async function refreshAccessToken(params) {
+  const url = params.tokenUrl ?? DEFAULT_TOKEN_URL;
+  const fetchFn = params.fetchImpl ?? globalThis.fetch;
+  const res = await fetchFn(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json"
+    },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: params.clientId,
+      client_secret: params.clientSecret,
+      refresh_token: params.refreshToken
+    }).toString()
+  });
+  return parseTokenResponse(res);
+}
+async function parseTokenResponse(res) {
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(
+      `MP OAuth ${res.status}: ${text.slice(0, 300)}`
+    );
+  }
+  const json = JSON.parse(text);
+  return OAuthTokenSchema.parse(json);
+}
+function expirationTimeMs(issuedAtMs, expiresInSeconds) {
+  return issuedAtMs + (expiresInSeconds ?? 21600) * 1e3;
+}
+function isExpiringSoon(expirationMs, skewSeconds = 300) {
+  return Date.now() + skewSeconds * 1e3 >= expirationMs;
+}
+function parseWebhookEvent(body, searchParams) {
+  const parseResult = WebhookBodySchema.safeParse(body ?? {});
+  const parsedBody = parseResult.success ? parseResult.data : {};
+  const topic = searchParams?.get("topic") ?? parsedBody.topic ?? parsedBody.type ?? null;
+  const dataId = searchParams?.get("id") ?? (parsedBody.data?.id !== void 0 ? String(parsedBody.data.id) : null) ?? parsedBody.resource ?? null;
+  if (!topic || !dataId) {
+    return null;
+  }
+  return {
+    topic,
+    dataId: String(dataId),
+    action: parsedBody.action ?? null,
+    raw: parsedBody
+  };
+}
+function verifyWebhookSignature(params) {
+  if (!params.signatureHeader || !params.requestId) return false;
+  const parts = Object.fromEntries(
+    params.signatureHeader.split(",").map((segment) => segment.trim().split("="))
+  );
+  const ts = parts.ts;
+  const v1 = parts.v1;
+  if (!ts || !v1) return false;
+  const manifest = `id:${params.dataId};request-id:${params.requestId};ts:${ts};`;
+  const expected = createHmac("sha256", params.secret).update(manifest).digest("hex");
+  if (expected.length !== v1.length) return false;
+  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
+}
+
+// src/tools.ts
 function deterministicIdempotencyKey(...parts) {
   const payload = parts.filter((p) => p !== void 0 && p !== null).map(String).join("|");
   return createHash("sha256").update(payload).digest("hex").slice(0, 32);
@@ -749,8 +1438,42 @@ var DEFAULT_DESCRIPTIONS = {
   // ── Saved-card charging (v0.3) ───────────────────────────────────────────
   charge_saved_card: "Charge a previously-saved card for a returning customer. Requires customer_id + card_id (from list_customer_cards) AND a fresh CVV the user provides this session. AR Mercado Pago does NOT support CVV-less charges via the public API \u2014 every charge needs CVV. Idempotent on (card_id, amount, external_reference): retries dedupe automatically. Returns the resulting Payment.",
   // ── QR in-store (v0.3) ───────────────────────────────────────────────────
-  create_qr_payment: "Generate a dynamic in-store QR for a buyer to scan with any AR wallet (Modo, BNA+, Cuenta DNI, Naranja X, Mercado Pago, etc. \u2014 interop is mandated by Transferencias 3.0). Requires a pre-configured POS external_id (one-time setup in MP dashboard). Returns the qr_data string + a base64 PNG data URL ready to display. The QR expires in `expires_in_seconds` (default 600). MP fires `point_integration_wh` then `payment` webhooks when scanned.",
-  cancel_qr_payment: "Cancel a pending QR order on a POS. Necessary if the buyer never scans \u2014 otherwise the next create_qr_payment on the same POS returns 409."
+  create_qr_payment: "Generate a dynamic in-store QR for a buyer to scan with any AR wallet (Modo, BNA+, Cuenta DNI, Naranja X, Mercado Pago, etc. \u2014 interop is mandated by Transferencias 3.0). Requires a pre-configured POS external_id (use create_pos to set one up first if needed). Returns the qr_data string + a base64 PNG data URL ready to display. The QR expires in `expires_in_seconds` (default 600). MP fires `point_integration_wh` then `payment` webhooks when scanned.",
+  cancel_qr_payment: "Cancel a pending QR order on a POS. Necessary if the buyer never scans \u2014 otherwise the next create_qr_payment on the same POS returns 409.",
+  // ── Subscription Plans (v0.4) ────────────────────────────────────────────
+  create_subscription_plan: "Create a REUSABLE subscription plan (preapproval_plan). Different from create_subscription: a plan defines price + frequency once, then customers subscribe to it via subscribe_to_plan. Use plans for SaaS-style billing (B\xE1sico/Pro/Enterprise tiers). For per-customer custom amounts, use create_subscription directly.",
+  list_subscription_plans: "List all subscription plans defined for this MP account. Useful before create_subscription_plan to check if one already exists, or for surfacing options to a customer.",
+  update_subscription_plan: "Update a subscription plan's reason / amount / status / back_url. Existing customer subscriptions to the plan are NOT automatically updated \u2014 only NEW subscribers get the new pricing.",
+  subscribe_to_plan: "Subscribe a customer to an existing reusable plan. Returns a Preapproval with init_point URL where the customer completes first payment. Cleaner than create_subscription when you have fixed tiers.",
+  list_subscription_payments: "List the auto-charge attempts (authorized_payments) under a subscription. Useful for 'show me the cobros del \xFAltimo mes for this client' or to debug a failing recurring charge.",
+  // ── Stores + POS (v0.4) ──────────────────────────────────────────────────
+  create_store: "Create a store under the seller's MP account. Stores are the parent entity for POSes (which generate QR payments). Required ONE-TIME setup before create_pos. Pass a unique external_id and a display name.",
+  list_stores: "List all stores configured for this MP account. Use this to find an existing store_id before create_pos, or to surface store options to the agent.",
+  create_pos: "Create a POS (Point of Sale) under a store. The POS's external_id is what create_qr_payment uses. Each physical checkout / counter / agent typically has its own POS. Categories are MP-defined (default 621102 = Other Food and Beverage Services).",
+  list_pos: "List all POSes for the seller (or filtered by store_id). Use to find an existing POS before create_qr_payment, or to surface options.",
+  // ── Disputes (v0.4 — read-only) ──────────────────────────────────────────
+  list_payment_disputes: "List all disputes / chargebacks raised against a payment. Read-only \u2014 resolution is dashboard-only. Surface the dashboard URL `https://www.mercadopago.com.ar/disputes/{dispute_id}` to the user when they need to respond.",
+  get_dispute: "Get details of a specific dispute including reason, amount, resolution status. Read-only.",
+  // ── Lookup helpers (v0.4) ────────────────────────────────────────────────
+  list_identification_types: "List valid identification types for the seller's site. AR returns: DNI, CI, LE, LC, Otro, Pasaporte, CUIT, CUIL with their min/max length. Useful to validate an identification before passing to create_payment.",
+  list_issuers: "List card issuers (banks) that support a payment_method_id. Optionally filter by `bin` (first 6 digits of the card) for accurate issuer detection. Useful with calculate_installments \u2014 issuer-specific promos (e.g., Naranja Galicia 6 cuotas sin inter\xE9s) only appear when the issuer is identified.",
+  // ── Webhooks management (v0.4) ───────────────────────────────────────────
+  list_webhooks: "List all webhook subscriptions configured for this MP application. Use to see what topics + URLs are wired before adding new ones.",
+  create_webhook: "Subscribe a webhook URL to a MP topic (payment, subscription_authorized_payment, subscription_preapproval, merchant_order, point_integration_wh). MP will POST to this URL when events of that topic fire.",
+  update_webhook: "Update a webhook's URL or topic. Useful when you change deployment URLs without resubscribing from scratch.",
+  delete_webhook: "Delete a webhook subscription. MP stops POSTing to it immediately.",
+  // ── Webhook handler combo (v0.5) ─────────────────────────────────────────
+  handle_webhook: "Process an incoming MP webhook in ONE call: verify the HMAC-SHA256 signature, parse the event, and (optionally) auto-fetch the underlying resource (Payment, Subscription, Order). Returns the structured event PLUS the full resource. USE THIS in your webhook endpoint INSTEAD of chaining verify_webhook_signature + parse_webhook_event + get_payment manually. Pass the raw request body, x-signature header, x-request-id header, and your MP webhook secret. SAFE: returns { verified: false } when signature mismatches \u2014 caller should respond 401 and stop processing. WHEN auto_fetch is true (default), the resource is fetched as the SAME MP user the client is configured for (so for marketplace integrations, instantiate a per-seller client).",
+  // ── OAuth Marketplace (v0.5) ─────────────────────────────────────────────
+  oauth_authorize_url: "Build the URL the SELLER (third-party MP account) visits to authorize your marketplace app. Pass the seller's redirect uri (must be whitelisted in MP dev panel) and an opaque state token (CSRF protection \u2014 bind it to the user's session). PURE FUNCTION: no network. The seller approves, MP redirects them to your `redirect_uri?code=...&state=...`. Then call oauth_exchange_code with the code.",
+  oauth_exchange_code: "Exchange the authorization code (from the OAuth redirect) for an `OAuthToken`. Returns access_token, refresh_token, user_id, and expires_in. **PERSIST the entire response** \u2014 refresh_token is long-lived and the only way to keep the integration alive past 6h. Use the access_token to instantiate a per-seller MercadoPagoClient for marketplace flows.",
+  oauth_refresh_token: "Refresh a per-seller access_token using the saved refresh_token. Call PROACTIVELY before expires_in elapses, or REACTIVELY on a 401 from a per-seller MercadoPagoClient. Returns a fresh OAuthToken \u2014 persist the new refresh_token (MP often returns the same value, but always replace).",
+  // ── Order Management API (v0.5 — modern Order API) ───────────────────────
+  create_order: "Create a new Order via MP's modern Order Management API. DIFFERENT from create_payment_preference: Order is a transactional entity with explicit lifecycle (created \u2192 processed \u2192 captured/canceled), supports MANUAL CAPTURE (auth-only, capture later \u2014 for ride-share, hotels, marketplaces) and aggregates multiple payments into one Order. Use Preference (Checkout Pro) for simple hosted pay-links; use Order when you need auth-only or multi-payment-per-order semantics. For marketplace splits, set marketplace + marketplace_fee + collector_id (the SELLER's MP user_id from oauth_exchange_code).",
+  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."
 };
 function mercadoPagoTools(client, options) {
   const desc = (name) => options.descriptions?.[name] ?? DEFAULT_DESCRIPTIONS[name];
@@ -1340,25 +2063,722 @@ function mercadoPagoTools(client, options) {
           width: 512
         });
         return {
-          in_store_order_id: qr.in_store_order_id,
-          qr_data: qr.qr_data,
-          qr_data_url: qrDataUrl,
-          expires_at: expiresAt,
-          external_pos_id: input.external_pos_id,
-          amount: input.amount_ars,
-          next_step: "Display the qr_data_url image to the buyer. Wait for the payment webhook (point_integration_wh fires first, then payment topic). If buyer doesn't scan in time, call cancel_qr_payment to free the POS."
+          in_store_order_id: qr.in_store_order_id,
+          qr_data: qr.qr_data,
+          qr_data_url: qrDataUrl,
+          expires_at: expiresAt,
+          external_pos_id: input.external_pos_id,
+          amount: input.amount_ars,
+          next_step: "Display the qr_data_url image to the buyer. Wait for the payment webhook (point_integration_wh fires first, then payment topic). If buyer doesn't scan in time, call cancel_qr_payment to free the POS."
+        };
+      }
+    }),
+    cancel_qr_payment: tool({
+      description: desc("cancel_qr_payment"),
+      inputSchema: z.object({
+        external_pos_id: z.string()
+      }),
+      execute: async ({ external_pos_id }) => {
+        const me = await client.getMe();
+        await client.cancelQrPayment(String(me.id), external_pos_id);
+        return { external_pos_id, cancelled: true };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Subscription Plans (v0.4)
+    // ─────────────────────────────────────────────────────────────────────────
+    create_subscription_plan: tool({
+      description: desc("create_subscription_plan"),
+      inputSchema: z.object({
+        reason: z.string().min(3).max(120).describe("Plan name shown at checkout"),
+        amount_ars: z.number().positive(),
+        frequency_months: z.number().int().min(1).max(12),
+        back_url: z.string().url().describe("HTTPS URL where MP redirects after first payment"),
+        external_reference: z.string().optional(),
+        free_trial_days: z.number().int().min(1).max(60).optional().describe("Free trial period in days before first charge")
+      }),
+      execute: async (input) => {
+        const plan = await client.createSubscriptionPlan({
+          reason: input.reason,
+          amount: input.amount_ars,
+          currency: "ARS",
+          frequency: input.frequency_months,
+          frequencyType: "months",
+          backUrl: input.back_url,
+          ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
+          ...input.free_trial_days !== void 0 ? { freeTrialFrequency: input.free_trial_days, freeTrialFrequencyType: "days" } : {}
+        });
+        return {
+          plan_id: plan.id,
+          status: plan.status,
+          reason: plan.reason,
+          amount: plan.auto_recurring.transaction_amount,
+          currency: plan.auto_recurring.currency_id,
+          frequency: `${plan.auto_recurring.frequency} ${plan.auto_recurring.frequency_type}`,
+          external_reference: plan.external_reference,
+          next_step: "Use subscribe_to_plan to enroll customers in this plan, or share its ID for them to subscribe via your frontend."
+        };
+      }
+    }),
+    list_subscription_plans: tool({
+      description: desc("list_subscription_plans"),
+      inputSchema: z.object({
+        status: z.string().optional(),
+        limit: z.number().int().min(1).max(100).optional()
+      }),
+      execute: async (input) => {
+        const result = await client.listSubscriptionPlans({
+          ...input.status !== void 0 ? { status: input.status } : {},
+          ...input.limit !== void 0 ? { limit: input.limit } : {}
+        });
+        return {
+          total: result.paging.total,
+          plans: result.results.map((p) => ({
+            plan_id: p.id,
+            reason: p.reason,
+            status: p.status,
+            amount: p.auto_recurring.transaction_amount,
+            currency: p.auto_recurring.currency_id,
+            frequency: `${p.auto_recurring.frequency} ${p.auto_recurring.frequency_type}`
+          }))
+        };
+      }
+    }),
+    update_subscription_plan: tool({
+      description: desc("update_subscription_plan"),
+      inputSchema: z.object({
+        plan_id: z.string(),
+        reason: z.string().optional(),
+        amount_ars: z.number().positive().optional(),
+        status: z.enum(["active", "cancelled"]).optional(),
+        back_url: z.string().url().optional()
+      }),
+      execute: async (input) => {
+        const updated = await client.updateSubscriptionPlan(input.plan_id, {
+          ...input.reason !== void 0 ? { reason: input.reason } : {},
+          ...input.amount_ars !== void 0 ? { amount: input.amount_ars } : {},
+          ...input.status !== void 0 ? { status: input.status } : {},
+          ...input.back_url !== void 0 ? { backUrl: input.back_url } : {}
+        });
+        return {
+          plan_id: updated.id,
+          status: updated.status,
+          reason: updated.reason,
+          amount: updated.auto_recurring.transaction_amount,
+          message: input.amount_ars !== void 0 ? "Updated. Existing subscribers keep their old amount; only NEW subscribers get the new pricing." : "Plan updated."
+        };
+      }
+    }),
+    subscribe_to_plan: tool({
+      description: desc("subscribe_to_plan"),
+      inputSchema: z.object({
+        plan_id: z.string(),
+        customer_email: z.string().email(),
+        external_reference: z.string().optional()
+      }),
+      execute: async (input) => {
+        const sub = await client.subscribeToPlan({
+          planId: input.plan_id,
+          payerEmail: input.customer_email,
+          ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {}
+        });
+        return {
+          subscription_id: sub.id,
+          status: sub.status,
+          payer_email: sub.payer_email,
+          init_point_url: sub.init_point,
+          next_step: "Send init_point_url to the customer for first payment with card+CVV."
+        };
+      }
+    }),
+    list_subscription_payments: tool({
+      description: desc("list_subscription_payments"),
+      inputSchema: z.object({
+        subscription_id: z.string(),
+        limit: z.number().int().min(1).max(100).optional()
+      }),
+      execute: async (input) => {
+        const result = await client.listSubscriptionPayments(input.subscription_id, {
+          ...input.limit !== void 0 ? { limit: input.limit } : {}
+        });
+        return {
+          subscription_id: input.subscription_id,
+          total: result.paging.total,
+          payments: result.results.map((p) => ({
+            authorized_payment_id: p.id,
+            payment_id: p.payment_id ?? null,
+            status: p.status,
+            amount: p.transaction_amount ?? null,
+            currency: p.currency_id ?? null,
+            debit_date: p.debit_date ?? null,
+            next_retry_date: p.next_retry_date ?? null,
+            retry_attempt: p.retry_attempt ?? 0,
+            reason: p.reason ?? null
+          }))
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Stores + POS (v0.4)
+    // ─────────────────────────────────────────────────────────────────────────
+    create_store: tool({
+      description: desc("create_store"),
+      inputSchema: z.object({
+        name: z.string().min(1).max(80),
+        external_id: z.string().min(1).max(64).describe("Unique within the seller's stores"),
+        address_line: z.string().optional(),
+        city_name: z.string().optional(),
+        state_name: z.string().optional()
+      }),
+      execute: async (input) => {
+        const me = await client.getMe();
+        const store = await client.createStore(String(me.id), {
+          name: input.name,
+          externalId: input.external_id,
+          ...input.address_line || input.city_name || input.state_name ? {
+            location: {
+              ...input.address_line ? { addressLine: input.address_line } : {},
+              ...input.city_name ? { cityName: input.city_name } : {},
+              ...input.state_name ? { stateName: input.state_name } : {},
+              countryId: "AR"
+            }
+          } : {}
+        });
+        return {
+          store_id: store.id,
+          name: store.name,
+          external_id: store.external_id,
+          next_step: "Use create_pos with this store_id to add a Point of Sale where create_qr_payment can issue QRs."
+        };
+      }
+    }),
+    list_stores: tool({
+      description: desc("list_stores"),
+      inputSchema: z.object({
+        limit: z.number().int().min(1).max(100).optional()
+      }),
+      execute: async (input) => {
+        const me = await client.getMe();
+        const result = await client.listStores(String(me.id), {
+          ...input.limit !== void 0 ? { limit: input.limit } : {}
+        });
+        return {
+          total: result.paging.total,
+          stores: result.results.map((s) => ({
+            store_id: s.id,
+            name: s.name ?? null,
+            external_id: s.external_id ?? null
+          }))
+        };
+      }
+    }),
+    create_pos: tool({
+      description: desc("create_pos"),
+      inputSchema: z.object({
+        name: z.string().min(1).max(80),
+        external_id: z.string().min(1).max(64).describe("Unique within the store. This is what create_qr_payment uses."),
+        store_id: z.string().describe("From create_store / list_stores"),
+        category: z.number().int().optional().describe("MP category code, default 621102 (other food/beverage)"),
+        fixed_amount: z.boolean().optional().describe("True for static QR with fixed amount; false (default) for dynamic per-order QR")
+      }),
+      execute: async (input) => {
+        const pos = await client.createPos({
+          name: input.name,
+          externalId: input.external_id,
+          storeId: input.store_id,
+          ...input.category !== void 0 ? { category: input.category } : {},
+          ...input.fixed_amount !== void 0 ? { fixedAmount: input.fixed_amount } : {}
+        });
+        return {
+          pos_id: pos.id,
+          external_id: pos.external_id,
+          store_id: pos.store_id,
+          name: pos.name,
+          next_step: "Use create_qr_payment with this external_id to start issuing dynamic QRs from this POS."
+        };
+      }
+    }),
+    list_pos: tool({
+      description: desc("list_pos"),
+      inputSchema: z.object({
+        store_id: z.string().optional(),
+        limit: z.number().int().min(1).max(100).optional()
+      }),
+      execute: async (input) => {
+        const result = await client.listPos({
+          ...input.store_id !== void 0 ? { storeId: input.store_id } : {},
+          ...input.limit !== void 0 ? { limit: input.limit } : {}
+        });
+        return {
+          total: result.paging.total,
+          pos: result.results.map((p) => ({
+            pos_id: p.id,
+            external_id: p.external_id ?? null,
+            store_id: p.store_id ?? null,
+            name: p.name ?? null
+          }))
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Disputes (v0.4 — read-only)
+    // ─────────────────────────────────────────────────────────────────────────
+    list_payment_disputes: tool({
+      description: desc("list_payment_disputes"),
+      inputSchema: z.object({ payment_id: z.string() }),
+      execute: async ({ payment_id }) => {
+        const disputes = await client.listPaymentDisputes(payment_id);
+        return {
+          payment_id,
+          count: disputes.length,
+          disputes: disputes.map((d) => ({
+            dispute_id: d.id,
+            status: d.status,
+            amount: d.amount ?? null,
+            reason: d.reason ?? null,
+            date_created: d.date_created ?? null,
+            dashboard_url: `https://www.mercadopago.com.ar/disputes/${d.id}`
+          }))
+        };
+      }
+    }),
+    get_dispute: tool({
+      description: desc("get_dispute"),
+      inputSchema: z.object({
+        payment_id: z.string(),
+        dispute_id: z.string()
+      }),
+      execute: async ({ payment_id, dispute_id }) => {
+        const d = await client.getDispute(payment_id, dispute_id);
+        return {
+          dispute_id: d.id,
+          status: d.status,
+          amount: d.amount ?? null,
+          reason: d.reason ?? null,
+          reason_description: d.reason_description ?? null,
+          resolution: d.resolution ?? null,
+          date_created: d.date_created ?? null,
+          dashboard_url: `https://www.mercadopago.com.ar/disputes/${d.id}`
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Lookup helpers (v0.4)
+    // ─────────────────────────────────────────────────────────────────────────
+    list_identification_types: tool({
+      description: desc("list_identification_types"),
+      inputSchema: z.object({}),
+      execute: async () => {
+        const types = await client.listIdentificationTypes();
+        return {
+          count: types.length,
+          types: types.map((t) => ({
+            id: t.id,
+            name: t.name,
+            type: t.type,
+            min_length: t.min_length ?? null,
+            max_length: t.max_length ?? null
+          }))
+        };
+      }
+    }),
+    list_issuers: tool({
+      description: desc("list_issuers"),
+      inputSchema: z.object({
+        payment_method_id: z.string().describe("E.g. 'visa', 'master', 'naranja'"),
+        bin: z.string().min(6).max(8).optional().describe("First 6-8 digits of card for precise issuer detection")
+      }),
+      execute: async (input) => {
+        const issuers = await client.listIssuers({
+          paymentMethodId: input.payment_method_id,
+          ...input.bin !== void 0 ? { bin: input.bin } : {}
+        });
+        return {
+          payment_method_id: input.payment_method_id,
+          count: issuers.length,
+          issuers: issuers.map((i) => ({
+            issuer_id: i.id,
+            name: i.name,
+            status: i.status ?? null
+          }))
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Webhooks management (v0.4)
+    // ─────────────────────────────────────────────────────────────────────────
+    list_webhooks: tool({
+      description: desc("list_webhooks"),
+      inputSchema: z.object({}),
+      execute: async () => {
+        const hooks = await client.listWebhooks();
+        return {
+          count: hooks.length,
+          webhooks: hooks.map((h) => ({
+            webhook_id: h.id,
+            url: h.url ?? null,
+            topic: h.topic ?? null,
+            status: h.status ?? null,
+            date_created: h.date_created ?? null
+          }))
+        };
+      }
+    }),
+    create_webhook: tool({
+      description: desc("create_webhook"),
+      inputSchema: z.object({
+        url: z.string().url(),
+        topic: z.string().describe("E.g. 'payment', 'subscription_authorized_payment', 'subscription_preapproval', 'merchant_order', 'point_integration_wh'")
+      }),
+      execute: async ({ url, topic }) => {
+        const hook = await client.createWebhook({ url, topic });
+        return {
+          webhook_id: hook.id,
+          url: hook.url ?? url,
+          topic: hook.topic ?? topic,
+          status: hook.status ?? null
+        };
+      }
+    }),
+    update_webhook: tool({
+      description: desc("update_webhook"),
+      inputSchema: z.object({
+        webhook_id: z.string(),
+        url: z.string().url().optional(),
+        topic: z.string().optional()
+      }),
+      execute: async (input) => {
+        const hook = await client.updateWebhook(input.webhook_id, {
+          ...input.url !== void 0 ? { url: input.url } : {},
+          ...input.topic !== void 0 ? { topic: input.topic } : {}
+        });
+        return {
+          webhook_id: hook.id,
+          url: hook.url ?? null,
+          topic: hook.topic ?? null,
+          status: hook.status ?? null
+        };
+      }
+    }),
+    delete_webhook: tool({
+      description: desc("delete_webhook"),
+      inputSchema: z.object({ webhook_id: z.string() }),
+      execute: async ({ webhook_id }) => {
+        await client.deleteWebhook(webhook_id);
+        return { webhook_id, deleted: true };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.5 — Webhook handler combo
+    // ─────────────────────────────────────────────────────────────────────────
+    handle_webhook: tool({
+      description: desc("handle_webhook"),
+      inputSchema: z.object({
+        raw_body: z.string().describe(
+          "The raw JSON body of the webhook request, exactly as received (do NOT re-stringify). Pass `await req.text()` from your handler."
+        ),
+        signature_header: z.string().nullable().describe("Value of the `x-signature` request header."),
+        request_id_header: z.string().nullable().describe("Value of the `x-request-id` request header."),
+        auto_fetch: z.boolean().optional().default(true).describe(
+          "If true (default), fetch the underlying resource (Payment, Subscription, etc.) AS the MP user the client is configured for. Set to false to skip the fetch (faster, useful when you only need the topic+id)."
+        )
+      }),
+      execute: async ({
+        raw_body,
+        signature_header,
+        request_id_header,
+        auto_fetch
+      }) => {
+        if (!options.webhookSecret) {
+          return {
+            verified: false,
+            error: "webhookSecret not configured in mercadoPagoTools options. Pass it from MP dev panel \u2192 Notificaciones \u2192 Webhooks.",
+            event: null,
+            resource: null
+          };
+        }
+        let parsedBody;
+        try {
+          parsedBody = JSON.parse(raw_body);
+        } catch {
+          return {
+            verified: false,
+            error: "raw_body is not valid JSON.",
+            event: null,
+            resource: null
+          };
+        }
+        const event = parseWebhookEvent(parsedBody);
+        if (!event) {
+          return {
+            verified: false,
+            error: "Could not extract topic + dataId from webhook body.",
+            event: null,
+            resource: null
+          };
+        }
+        const verified = verifyWebhookSignature({
+          requestId: request_id_header,
+          dataId: event.dataId,
+          signatureHeader: signature_header,
+          secret: options.webhookSecret
+        });
+        if (!verified) {
+          return {
+            verified: false,
+            error: "HMAC-SHA256 signature mismatch. Reject the webhook (HTTP 401).",
+            event,
+            resource: null
+          };
+        }
+        let resource = null;
+        let resourceError = null;
+        if (auto_fetch) {
+          try {
+            switch (event.topic) {
+              case "payment":
+              case "payment.created":
+              case "payment.updated":
+                resource = await client.getPayment(event.dataId);
+                break;
+              case "preapproval":
+              case "subscription_preapproval":
+                resource = await client.getPreapproval(event.dataId);
+                break;
+              case "subscription_authorized_payment":
+                resource = { id: event.dataId, hint: "Use list_subscription_payments to enumerate parent." };
+                break;
+              default:
+                resource = null;
+                resourceError = `No auto-fetch handler for topic '${event.topic}' yet.`;
+            }
+          } catch (err) {
+            resourceError = err instanceof Error ? err.message : String(err);
+          }
+        }
+        return {
+          verified: true,
+          event,
+          resource,
+          resource_error: resourceError
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.5 — OAuth Marketplace flow
+    // ─────────────────────────────────────────────────────────────────────────
+    oauth_authorize_url: tool({
+      description: desc("oauth_authorize_url"),
+      inputSchema: z.object({
+        redirect_uri: z.string().url().describe(
+          "Where MP redirects the seller after approval. MUST be whitelisted in MP dev panel \u2192 Aplicaciones \u2192 tu app \u2192 Redirect URIs."
+        ),
+        state: z.string().min(8).describe(
+          "Opaque CSRF/session token echoed back. Bind to the user's session and verify on redirect."
+        )
+      }),
+      execute: async ({ redirect_uri, state }) => {
+        if (!options.oauth?.clientId) {
+          return {
+            available: false,
+            error: "OAuth not configured. Pass `oauth: { clientId, clientSecret }` to mercadoPagoTools options.",
+            url: null
+          };
+        }
+        const url = buildAuthorizeUrl({
+          clientId: options.oauth.clientId,
+          redirectUri: redirect_uri,
+          state
+        });
+        return {
+          available: true,
+          url,
+          next_step: "Redirect the seller to `url`. After approval MP sends them to redirect_uri?code=...&state=... \u2014 verify state matches, then call oauth_exchange_code with the code."
+        };
+      }
+    }),
+    oauth_exchange_code: tool({
+      description: desc("oauth_exchange_code"),
+      inputSchema: z.object({
+        code: z.string().describe("The `code` query param from the OAuth redirect URL."),
+        redirect_uri: z.string().url().describe(
+          "Must EXACTLY match the redirect_uri used in oauth_authorize_url."
+        )
+      }),
+      execute: async ({ code, redirect_uri }) => {
+        if (!options.oauth?.clientId || !options.oauth?.clientSecret) {
+          return {
+            available: false,
+            error: "OAuth not configured. Pass `oauth: { clientId, clientSecret }` to mercadoPagoTools options.",
+            token: null
+          };
+        }
+        try {
+          const token = await exchangeCodeForToken({
+            clientId: options.oauth.clientId,
+            clientSecret: options.oauth.clientSecret,
+            code,
+            redirectUri: redirect_uri
+          });
+          return {
+            available: true,
+            token,
+            next_step: "PERSIST { user_id, access_token, refresh_token, expires_in } against this seller. Use access_token to instantiate `new MercadoPagoClient({ accessToken })` AS the seller for marketplace API calls."
+          };
+        } catch (err) {
+          return {
+            available: true,
+            error: err instanceof Error ? err.message : String(err),
+            token: null
+          };
+        }
+      }
+    }),
+    oauth_refresh_token: tool({
+      description: desc("oauth_refresh_token"),
+      inputSchema: z.object({
+        refresh_token: z.string().describe("The saved refresh_token for this seller.")
+      }),
+      execute: async ({ refresh_token }) => {
+        if (!options.oauth?.clientId || !options.oauth?.clientSecret) {
+          return {
+            available: false,
+            error: "OAuth not configured. Pass `oauth: { clientId, clientSecret }` to mercadoPagoTools options.",
+            token: null
+          };
+        }
+        try {
+          const token = await refreshAccessToken({
+            clientId: options.oauth.clientId,
+            clientSecret: options.oauth.clientSecret,
+            refreshToken: refresh_token
+          });
+          return {
+            available: true,
+            token,
+            next_step: "Replace the persisted access_token + refresh_token with these new values (refresh_token may have rotated)."
+          };
+        } catch (err) {
+          return {
+            available: true,
+            error: err instanceof Error ? err.message : String(err),
+            token: null
+          };
+        }
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // v0.5 — Order Management API
+    // ─────────────────────────────────────────────────────────────────────────
+    create_order: tool({
+      description: desc("create_order"),
+      inputSchema: z.object({
+        type: z.enum(["online", "in_store"]).describe("'online' for hosted/checkout flow, 'in_store' for QR/POS"),
+        currency_id: z.string().optional().default("ARS"),
+        external_reference: z.string().optional(),
+        total_amount: z.number().positive().optional(),
+        items: z.array(
+          z.object({
+            title: z.string(),
+            unit_price: z.number(),
+            quantity: z.number(),
+            description: z.string().optional()
+          })
+        ).optional(),
+        payer_email: z.string().email().optional(),
+        capture_mode: z.enum(["automatic", "manual"]).optional().describe(
+          "'automatic' charges immediately; 'manual' authorizes only \u2014 capture later via capture_order."
+        ),
+        notification_url: z.string().url().optional(),
+        marketplace: z.string().optional().describe(
+          "Marketplace identifier (your app's name). Required for split payments."
+        ),
+        marketplace_fee: z.number().optional().describe(
+          "Fee in ARS (NOT %) credited to the marketplace's MP account."
+        ),
+        collector_id: z.union([z.string(), z.number()]).optional().describe(
+          "Seller's MP user_id (from oauth_exchange_code.user_id). Funds route here; marketplace_fee is split off to your account."
+        )
+      }),
+      execute: async (input) => {
+        const params = {
+          type: input.type
+        };
+        if (input.currency_id) params.currency_id = input.currency_id;
+        if (input.external_reference) params.external_reference = input.external_reference;
+        if (input.total_amount !== void 0) params.total_amount = input.total_amount;
+        if (input.items) params.items = input.items;
+        if (input.payer_email) params.payer = { email: input.payer_email };
+        if (input.capture_mode) params.capture_mode = input.capture_mode;
+        if (input.notification_url) params.notification_url = input.notification_url;
+        if (input.marketplace) params.marketplace = input.marketplace;
+        if (input.marketplace_fee !== void 0) params.marketplace_fee = input.marketplace_fee;
+        if (input.collector_id !== void 0) params.collector_id = input.collector_id;
+        const order = await client.createOrder(params, {
+          idempotencyKey: deterministicIdempotencyKey(
+            "create_order",
+            input.external_reference,
+            input.total_amount,
+            input.collector_id
+          )
+        });
+        return {
+          order_id: order.id,
+          status: order.status ?? null,
+          capture_mode: order.capture_mode ?? params.capture_mode ?? "automatic",
+          total_amount: order.total_amount ?? null
         };
       }
     }),
-    cancel_qr_payment: tool({
-      description: desc("cancel_qr_payment"),
+    get_order: tool({
+      description: desc("get_order"),
+      inputSchema: z.object({ order_id: z.string() }),
+      execute: async ({ order_id }) => {
+        const order = await client.getOrder(order_id);
+        return order;
+      }
+    }),
+    update_order: tool({
+      description: desc("update_order"),
       inputSchema: z.object({
-        external_pos_id: z.string()
+        order_id: z.string(),
+        external_reference: z.string().optional(),
+        total_amount: z.number().optional()
       }),
-      execute: async ({ external_pos_id }) => {
-        const me = await client.getMe();
-        await client.cancelQrPayment(String(me.id), external_pos_id);
-        return { external_pos_id, cancelled: true };
+      execute: async ({ order_id, external_reference, total_amount }) => {
+        const patch = {};
+        if (external_reference !== void 0) patch.external_reference = external_reference;
+        if (total_amount !== void 0) patch.total_amount = total_amount;
+        const order = await client.updateOrder(order_id, patch);
+        return order;
+      }
+    }),
+    capture_order: tool({
+      description: desc("capture_order"),
+      inputSchema: z.object({
+        order_id: z.string(),
+        amount: z.number().positive().optional().describe(
+          "Optional partial-capture amount. Omit to capture the full authorized amount."
+        )
+      }),
+      execute: async ({ order_id, amount }) => {
+        const order = await client.captureOrder(order_id, amount);
+        return {
+          order_id: order.id,
+          status: order.status ?? null,
+          captured_amount: amount ?? order.total_amount ?? null
+        };
+      }
+    }),
+    cancel_order: tool({
+      description: desc("cancel_order"),
+      inputSchema: z.object({ order_id: z.string() }),
+      execute: async ({ order_id }) => {
+        const order = await client.cancelOrder(order_id);
+        return {
+          order_id: order.id,
+          status: order.status ?? "canceled"
+        };
       }
     })
   };
@@ -1382,235 +2802,7 @@ var InMemoryStateAdapter = class {
     this.store.clear();
   }
 };
-z.enum(["MLA", "MLB", "MLM", "MCO", "MLC", "MLU"]);
-var CurrencyIdSchema = z.enum(["ARS", "USD", "BRL", "MXN"]);
-var FrequencyTypeSchema = z.enum(["months", "days"]);
-var PreapprovalStatusSchema = z.union([
-  z.literal("pending"),
-  z.literal("authorized"),
-  z.literal("paused"),
-  z.literal("cancelled"),
-  z.string()
-]);
-var AutoRecurringSchema = z.object({
-  frequency: z.number().int().positive(),
-  frequency_type: FrequencyTypeSchema,
-  transaction_amount: z.number().positive(),
-  currency_id: CurrencyIdSchema,
-  start_date: z.string().optional(),
-  end_date: z.string().optional()
-});
-z.object({
-  id: z.string(),
-  status: PreapprovalStatusSchema,
-  payer_email: z.string(),
-  init_point: z.string().url(),
-  external_reference: z.string().optional(),
-  date_created: z.string(),
-  last_modified: z.string(),
-  next_payment_date: z.string().optional(),
-  payer_id: z.union([z.string(), z.number()]).optional(),
-  auto_recurring: AutoRecurringSchema
-});
-var WebhookBodySchema = z.object({
-  type: z.string().optional(),
-  topic: z.string().optional(),
-  action: z.string().optional(),
-  data: z.object({ id: z.union([z.string(), z.number()]) }).optional(),
-  resource: z.string().optional(),
-  user_id: z.union([z.string(), z.number()]).optional(),
-  api_version: z.string().optional(),
-  date_created: z.string().optional(),
-  id: z.union([z.string(), z.number()]).optional(),
-  live_mode: z.boolean().optional()
-}).passthrough();
-var PaymentStatusSchema = z.union([
-  z.literal("pending"),
-  z.literal("approved"),
-  z.literal("authorized"),
-  z.literal("in_process"),
-  z.literal("in_mediation"),
-  z.literal("rejected"),
-  z.literal("cancelled"),
-  z.literal("refunded"),
-  z.literal("charged_back"),
-  z.string()
-]);
-var PaymentSchema = z.object({
-  id: z.union([z.string(), z.number()]).transform(String),
-  status: PaymentStatusSchema,
-  status_detail: z.string().nullable().optional(),
-  date_created: z.string().nullable().optional(),
-  date_approved: z.string().nullable().optional(),
-  date_last_updated: z.string().nullable().optional(),
-  transaction_amount: z.number(),
-  currency_id: z.string(),
-  installments: z.number().int().nullable().optional(),
-  payment_method_id: z.string().nullable().optional(),
-  payment_type_id: z.string().nullable().optional(),
-  external_reference: z.string().nullable().optional(),
-  description: z.string().nullable().optional(),
-  payer: z.object({
-    id: z.union([z.string(), z.number()]).optional(),
-    email: z.string().nullable().optional(),
-    identification: z.object({
-      type: z.string().nullable().optional(),
-      number: z.string().nullable().optional()
-    }).nullable().optional()
-  }).passthrough().optional(),
-  transaction_details: z.object({
-    net_received_amount: z.number().nullable().optional(),
-    total_paid_amount: z.number().nullable().optional(),
-    installment_amount: z.number().nullable().optional()
-  }).passthrough().optional()
-}).passthrough();
-z.object({
-  paging: z.object({
-    total: z.number(),
-    limit: z.number(),
-    offset: z.number()
-  }),
-  results: z.array(PaymentSchema)
-});
-z.object({
-  id: z.union([z.string(), z.number()]).transform(String),
-  payment_id: z.union([z.string(), z.number()]).transform(String),
-  amount: z.number(),
-  source: z.object({
-    id: z.string().nullable().optional(),
-    name: z.string().nullable().optional(),
-    type: z.string().nullable().optional()
-  }).nullable().optional(),
-  date_created: z.string().nullable().optional(),
-  status: z.string().nullable().optional()
-}).passthrough();
-var PreferenceItemSchema = z.object({
-  id: z.string().optional(),
-  title: z.string(),
-  description: z.string().optional(),
-  picture_url: z.string().url().optional(),
-  category_id: z.string().optional(),
-  quantity: z.number().int().positive(),
-  unit_price: z.number().positive(),
-  currency_id: CurrencyIdSchema.optional()
-});
-z.object({
-  id: z.string(),
-  init_point: z.string().url().optional(),
-  sandbox_init_point: z.string().url().optional(),
-  client_id: z.union([z.string(), z.number()]).optional(),
-  collector_id: z.union([z.string(), z.number()]).optional(),
-  items: z.array(PreferenceItemSchema).optional(),
-  external_reference: z.string().nullable().optional(),
-  date_created: z.string().nullable().optional(),
-  expires: z.boolean().optional(),
-  expiration_date_from: z.string().nullable().optional(),
-  expiration_date_to: z.string().nullable().optional()
-}).passthrough();
-z.object({
-  id: z.string(),
-  email: z.string(),
-  first_name: z.string().nullable().optional(),
-  last_name: z.string().nullable().optional(),
-  phone: z.object({ area_code: z.string().nullable().optional(), number: z.string().nullable().optional() }).nullable().optional(),
-  identification: z.object({ type: z.string().nullable().optional(), number: z.string().nullable().optional() }).nullable().optional(),
-  date_created: z.string().nullable().optional(),
-  date_last_updated: z.string().nullable().optional(),
-  description: z.string().nullable().optional()
-}).passthrough();
-z.object({
-  id: z.string(),
-  customer_id: z.string(),
-  expiration_month: z.number().int().nullable().optional(),
-  expiration_year: z.number().int().nullable().optional(),
-  first_six_digits: z.string().nullable().optional(),
-  last_four_digits: z.string().nullable().optional(),
-  payment_method: z.object({
-    id: z.string().nullable().optional(),
-    name: z.string().nullable().optional(),
-    payment_type_id: z.string().nullable().optional()
-  }).nullable().optional(),
-  date_created: z.string().nullable().optional()
-}).passthrough();
-z.object({
-  id: z.string(),
-  name: z.string(),
-  payment_type_id: z.string(),
-  status: z.string(),
-  thumbnail: z.string().nullable().optional(),
-  secure_thumbnail: z.string().nullable().optional(),
-  min_allowed_amount: z.number().nullable().optional(),
-  max_allowed_amount: z.number().nullable().optional()
-}).passthrough();
-z.object({
-  payment_method_id: z.string(),
-  payment_type_id: z.string(),
-  issuer: z.object({
-    id: z.union([z.string(), z.number()]).optional(),
-    name: z.string().nullable().optional()
-  }).nullable().optional(),
-  payer_costs: z.array(
-    z.object({
-      installments: z.number().int(),
-      installment_rate: z.number(),
-      discount_rate: z.number().nullable().optional(),
-      installment_amount: z.number(),
-      total_amount: z.number(),
-      recommended_message: z.string().nullable().optional()
-    }).passthrough()
-  )
-}).passthrough();
-z.object({
-  in_store_order_id: z.string(),
-  qr_data: z.string()
-}).passthrough();
-z.object({
-  id: z.string(),
-  status: z.string().optional(),
-  date_due: z.string().optional(),
-  card_id: z.string().optional(),
-  cardholder: z.unknown().optional()
-}).passthrough();
-z.object({
-  id: z.union([z.string(), z.number()]).transform(String),
-  email: z.string().nullable().optional(),
-  nickname: z.string().nullable().optional(),
-  country_id: z.string().nullable().optional(),
-  site_id: z.string().nullable().optional(),
-  user_type: z.string().nullable().optional(),
-  status: z.object({ user_type: z.string().nullable().optional() }).passthrough().nullable().optional()
-}).passthrough();
-
-// src/webhook.ts
-function parseWebhookEvent(body, searchParams) {
-  const parseResult = WebhookBodySchema.safeParse(body ?? {});
-  const parsedBody = parseResult.success ? parseResult.data : {};
-  const topic = searchParams?.get("topic") ?? parsedBody.topic ?? parsedBody.type ?? null;
-  const dataId = searchParams?.get("id") ?? (parsedBody.data?.id !== void 0 ? String(parsedBody.data.id) : null) ?? parsedBody.resource ?? null;
-  if (!topic || !dataId) {
-    return null;
-  }
-  return {
-    topic,
-    dataId: String(dataId),
-    action: parsedBody.action ?? null,
-    raw: parsedBody
-  };
-}
-function verifyWebhookSignature(params) {
-  if (!params.signatureHeader || !params.requestId) return false;
-  const parts = Object.fromEntries(
-    params.signatureHeader.split(",").map((segment) => segment.trim().split("="))
-  );
-  const ts = parts.ts;
-  const v1 = parts.v1;
-  if (!ts || !v1) return false;
-  const manifest = `id:${params.dataId};request-id:${params.requestId};ts:${ts};`;
-  const expected = createHmac("sha256", params.secret).update(manifest).digest("hex");
-  if (expected.length !== v1.length) return false;
-  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
-}
 
-export { InMemoryStateAdapter, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, classifyError, mercadoPagoTools, parseWebhookEvent, verifyWebhookSignature };
+export { InMemoryStateAdapter, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, buildAuthorizeUrl, classifyError, exchangeCodeForToken, expirationTimeMs, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map