@ar-agents/mercadopago 0.8.0 → 0.9.0

package/dist/index.js

@@ -164,6 +164,8 @@ var MercadoPagoClient = class {
   requestTimeoutMs;
   maxRetries;
   onCall;
+  circuitBreaker;
+  traceContext;
   constructor(options) {
     if (!options.accessToken) {
       throw new Error(
@@ -176,8 +178,24 @@ var MercadoPagoClient = class {
     this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
     this.maxRetries = Math.max(0, options.maxRetries ?? 1);
     this.onCall = options.onCall;
+    this.circuitBreaker = options.circuitBreaker;
+    this.traceContext = options.traceContext;
+  }
+  /**
+   * v0.9 — Inspect the circuit breaker state (when configured). Returns
+   * `null` when no circuit breaker is wired. Useful for health checks.
+   */
+  getCircuitState() {
+    return this.circuitBreaker?.getStats() ?? null;
   }
   async request(method, path, body, options) {
+    const exec = () => this.requestUnprotected(method, path, body, options);
+    if (this.circuitBreaker) {
+      return this.circuitBreaker.execute(exec);
+    }
+    return exec();
+  }
+  async requestUnprotected(method, path, body, options) {
     const headers = {
       Authorization: `Bearer ${this.accessToken}`,
       "Content-Type": "application/json"
@@ -185,6 +203,11 @@ var MercadoPagoClient = class {
     if (options?.idempotencyKey) {
       headers["X-Idempotency-Key"] = options.idempotencyKey;
     }
+    const trace = this.traceContext?.();
+    if (trace?.traceId && trace?.spanId) {
+      const flags = (trace.traceFlags ?? 1).toString(16).padStart(2, "0");
+      headers["traceparent"] = `00-${trace.traceId}-${trace.spanId}-${flags}`;
+    }
     let url = `${this.baseUrl}${path}`;
     if (options?.query) {
       const search = new URLSearchParams();
@@ -201,24 +224,54 @@ var MercadoPagoClient = class {
     let attempt = 0;
     let lastError;
     let lastStatus = null;
+    const fireOnCall = (event) => {
+      const traceCtx = trace?.traceId ? {
+        traceId: trace.traceId,
+        ...trace.spanId !== void 0 ? { spanId: trace.spanId } : {}
+      } : void 0;
+      this.onCall?.({
+        method,
+        path,
+        durationMs: Date.now() - t0,
+        ...event,
+        ...this.circuitBreaker ? { circuitState: this.circuitBreaker.getState() } : {},
+        ...traceCtx ? { traceContext: traceCtx } : {}
+      });
+    };
     while (attempt <= this.maxRetries) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+      const parentSignal = options?.signal;
+      const onParentAbort = () => controller.abort();
+      if (parentSignal) {
+        if (parentSignal.aborted) {
+          clearTimeout(timer);
+          throw new MercadoPagoTimeoutError(path, 0);
+        }
+        parentSignal.addEventListener("abort", onParentAbort, { once: true });
+      }
       const init = { method, headers, signal: controller.signal };
       if (body !== void 0) init.body = JSON.stringify(body);
       try {
         const res = await fetchFn(url, init);
         clearTimeout(timer);
+        if (parentSignal) parentSignal.removeEventListener("abort", onParentAbort);
         lastStatus = res.status;
+        const requestId = res.headers.get("x-request-id");
+        const rlRemaining = res.headers.get("x-rate-limit-remaining");
+        const rlReset = res.headers.get("x-rate-limit-reset");
+        const rateLimit = {
+          remaining: rlRemaining !== null ? Number(rlRemaining) : null,
+          resetSeconds: rlReset !== null ? Number(rlReset) : null
+        };
         if (res.ok) {
           const text2 = await res.text();
-          this.onCall?.({
-            method,
-            path,
-            durationMs: Date.now() - t0,
+          fireOnCall({
+            success: true,
             httpStatus: res.status,
             retried: attempt,
-            success: true
+            requestId,
+            rateLimit
           });
           if (!text2) return void 0;
           return JSON.parse(text2);
@@ -233,13 +286,12 @@ var MercadoPagoClient = class {
         }
         const contentType = res.headers.get("content-type") ?? "";
         if (res.status >= 500 && !contentType.includes("application/json")) {
-          this.onCall?.({
-            method,
-            path,
-            durationMs: Date.now() - t0,
+          fireOnCall({
+            success: false,
             httpStatus: res.status,
             retried: attempt,
-            success: false
+            requestId,
+            rateLimit
           });
           throw new MercadoPagoOverloadedError(path, res.status);
         }
@@ -251,33 +303,33 @@ var MercadoPagoClient = class {
           parsed = text;
         }
         const err = classifyError(res.status, path, parsed, options?.classifyContext);
-        this.onCall?.({
-          method,
-          path,
-          durationMs: Date.now() - t0,
+        fireOnCall({
+          success: false,
           httpStatus: res.status,
           retried: attempt,
-          success: false
+          requestId,
+          rateLimit
         });
         throw err;
       } catch (err) {
         clearTimeout(timer);
+        if (parentSignal) parentSignal.removeEventListener("abort", onParentAbort);
         if (err instanceof MercadoPagoError) throw err;
         const isAbort = err instanceof Error && err.name === "AbortError";
+        const isParentAbort = parentSignal?.aborted ?? false;
         const isNetwork = !lastStatus && !isAbort;
-        if ((isNetwork || isAbort) && attempt < this.maxRetries) {
+        if ((isNetwork || isAbort && !isParentAbort) && attempt < this.maxRetries) {
           lastError = err;
           attempt++;
           await sleep(250 * Math.pow(2, attempt - 1));
           continue;
         }
-        this.onCall?.({
-          method,
-          path,
-          durationMs: Date.now() - t0,
+        fireOnCall({
+          success: false,
           httpStatus: lastStatus,
           retried: attempt,
-          success: false
+          requestId: null,
+          rateLimit: { remaining: null, resetSeconds: null }
         });
         if (isAbort) {
           throw new MercadoPagoTimeoutError(path, this.requestTimeoutMs);
@@ -1231,6 +1283,53 @@ var MercadoPagoClient = class {
     );
     return { id: intentId, canceled: true };
   }
+  // ──────────────────────────────────────────────────────────────────────────
+  // v0.9 — Health check
+  //
+  // No dedicated ping endpoint exists in MP's public API. We use `getMe()`
+  // (`/users/me`) as a lightweight liveness probe — it requires only a valid
+  // accessToken, returns ~200 bytes of JSON, and is the same call MP's own
+  // dashboard makes on startup. A successful response proves: (a) network
+  // path to MP is up, (b) accessToken is valid, (c) MP is responding.
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * Liveness probe against MP. Returns latency + circuit-breaker state.
+   * Use as a /health endpoint for k8s, Vercel cron, or status-page checks.
+   *
+   * Returns `{ ok: false, ... }` instead of throwing — designed for
+   * monitoring loops that want to keep running.
+   *
+   * @param signal Optional AbortSignal to cap wait time (e.g., 2s for
+   *               status-page polling).
+   */
+  async healthCheck(signal) {
+    const t0 = Date.now();
+    const circuitBefore = this.circuitBreaker?.getStats() ?? null;
+    try {
+      const me = await this.request(
+        "GET",
+        "/users/me",
+        void 0,
+        signal ? { signal } : {}
+      );
+      return {
+        ok: true,
+        latencyMs: Date.now() - t0,
+        userId: String(me.id),
+        error: null,
+        circuit: this.circuitBreaker?.getStats() ?? null
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        ok: false,
+        latencyMs: Date.now() - t0,
+        userId: null,
+        error: message,
+        circuit: this.circuitBreaker?.getStats() ?? circuitBefore
+      };
+    }
+  }
 };
 
 // src/crypto.ts
@@ -2298,7 +2397,9 @@ var DEFAULT_DESCRIPTIONS = {
   cancel_point_payment_intent: "Cancel an OPEN point payment intent before the buyer interacts with the device. ONLY WORKS while state='OPEN' \u2014 once the buyer taps, you can't cancel; refund_payment after the fact instead.",
   // ── Pure helpers (v0.7) ──────────────────────────────────────────────────
   compute_marketplace_fee: "PURE HELPER (no network) \u2014 given a transaction amount + fee rule (% or flat ARS, with optional min/max floors), returns the exact `marketplace_fee` value in ARS to pass to create_order or create_payment_preference. USE WHEN your platform takes a commission and you need to compute the exact fee per transaction. Examples: { percent: 5, minArs: 50, maxArs: 5000 } for percentage with floor + cap; { flatArs: 200, percent: 2 } for fixed + percentage.",
-  explain_payment_status: "PURE HELPER (no network) \u2014 given a Payment object (from get_payment / create_payment / handle_webhook), returns { summary, recommendedAction, final, paid, retryable } in Spanish. Translates MP's cryptic status_detail codes to plain Spanish + actionable guidance ('reintentar con otra tarjeta' vs 'esperar webhook' vs 'estado final'). USE THIS instead of having to memorize 30+ status_detail codes \u2014 surface summary + recommendedAction directly to the user."
+  explain_payment_status: "PURE HELPER (no network) \u2014 given a Payment object (from get_payment / create_payment / handle_webhook), returns { summary, recommendedAction, final, paid, retryable } in Spanish. Translates MP's cryptic status_detail codes to plain Spanish + actionable guidance ('reintentar con otra tarjeta' vs 'esperar webhook' vs 'estado final'). USE THIS instead of having to memorize 30+ status_detail codes \u2014 surface summary + recommendedAction directly to the user.",
+  // ── v0.9 — Health check + observability ──────────────────────────────────
+  mp_health_check: "Liveness probe against MP. Returns { ok, latencyMs, userId, circuit }. USE THIS as the first call in long-running agent workflows to verify (a) network path to MP is up, (b) accessToken is valid, (c) MP is responding. Circuit-breaker state included when configured \u2014 surface to ops dashboards. Returns ok=false instead of throwing \u2014 safe to call in monitoring loops without try/catch."
 };
 function mercadoPagoTools(client, options) {
   const desc = (name) => options.descriptions?.[name] ?? DEFAULT_DESCRIPTIONS[name];
@@ -4056,6 +4157,21 @@ function mercadoPagoTools(client, options) {
         };
       }
     }),
+    mp_health_check: tool({
+      description: desc("mp_health_check"),
+      inputSchema: z.object({
+        timeout_ms: z.number().int().positive().max(3e4).optional().describe("Cap the wait time (default 5s). Use lower for status-page polling.")
+      }),
+      execute: async ({ timeout_ms }) => {
+        const controller = new AbortController();
+        const t = setTimeout(() => controller.abort(), timeout_ms ?? 5e3);
+        try {
+          return await client.healthCheck(controller.signal);
+        } finally {
+          clearTimeout(t);
+        }
+      }
+    }),
     explain_payment_status: tool({
       description: desc("explain_payment_status"),
       inputSchema: z.object({
@@ -4146,6 +4262,164 @@ var InMemoryIdempotencyCache = class {
   }
 };
 
-export { InMemoryIdempotencyCache, InMemoryOAuthTokenStore, InMemoryStateAdapter, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, TEST_CARDS_AR, TEST_PAYERS_AR, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, computeMarketplaceFee, exchangeCodeForToken, expirationTimeMs, explainPaymentStatus, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
+// src/circuit-breaker.ts
+var CircuitOpenError = class extends Error {
+  constructor(retryAfterMs, consecutiveFailures) {
+    super(
+      `Circuit breaker is OPEN \u2014 failing fast. Retry in ${Math.ceil(
+        retryAfterMs / 1e3
+      )}s. Consecutive upstream failures: ${consecutiveFailures}.`
+    );
+    this.retryAfterMs = retryAfterMs;
+    this.consecutiveFailures = consecutiveFailures;
+    this.name = "CircuitOpenError";
+  }
+  retryAfterMs;
+  consecutiveFailures;
+};
+var CircuitBreaker = class {
+  state = "CLOSED";
+  consecutiveFailures = 0;
+  halfOpenSuccesses = 0;
+  openedAt = 0;
+  /** Timestamps of failures within the monitoring window. */
+  failureWindow = [];
+  failureThreshold;
+  successThreshold;
+  resetTimeoutMs;
+  monitoringWindowMs;
+  onStateChange;
+  isFailureFn;
+  now;
+  constructor(opts = {}) {
+    this.failureThreshold = opts.failureThreshold ?? 5;
+    this.successThreshold = opts.successThreshold ?? 2;
+    this.resetTimeoutMs = opts.resetTimeoutMs ?? 3e4;
+    this.monitoringWindowMs = opts.monitoringWindowMs ?? 6e4;
+    this.onStateChange = opts.onStateChange ?? null;
+    this.isFailureFn = opts.isFailure ?? (() => true);
+    this.now = opts.now ?? Date.now;
+  }
+  /** Read the current state. Useful for health checks + metrics. */
+  getState() {
+    if (this.state === "OPEN" && this.now() - this.openedAt >= this.resetTimeoutMs) {
+      this.transitionTo("HALF_OPEN");
+    }
+    return this.state;
+  }
+  /** Read diagnostic state for health checks + dashboards. */
+  getStats() {
+    const state = this.getState();
+    const msSinceOpened = this.openedAt > 0 ? this.now() - this.openedAt : null;
+    const msUntilHalfOpen = state === "OPEN" && msSinceOpened !== null ? Math.max(0, this.resetTimeoutMs - msSinceOpened) : null;
+    return {
+      state,
+      consecutiveFailures: this.consecutiveFailures,
+      failuresInWindow: this.failuresInCurrentWindow(),
+      msSinceOpened,
+      msUntilHalfOpen
+    };
+  }
+  /**
+   * Execute `fn` under the breaker's protection.
+   * - If the breaker is OPEN, throws `CircuitOpenError` immediately.
+   * - If `fn` succeeds, may transition HALF_OPEN → CLOSED.
+   * - If `fn` fails (and the error counts as a failure), records the
+   *   failure; may transition CLOSED → OPEN or HALF_OPEN → OPEN.
+   */
+  async execute(fn) {
+    const state = this.getState();
+    if (state === "OPEN") {
+      const elapsed = this.now() - this.openedAt;
+      throw new CircuitOpenError(
+        Math.max(0, this.resetTimeoutMs - elapsed),
+        this.consecutiveFailures
+      );
+    }
+    try {
+      const result = await fn();
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      if (this.isFailureFn(err)) {
+        this.recordFailure(err);
+      }
+      throw err;
+    }
+  }
+  /** Manually force the breaker open. Useful for runbook / manual ops. */
+  trip(reason) {
+    if (this.state !== "OPEN") {
+      this.transitionTo("OPEN", reason);
+    }
+  }
+  /** Manually reset the breaker to CLOSED. */
+  reset() {
+    this.consecutiveFailures = 0;
+    this.halfOpenSuccesses = 0;
+    this.failureWindow = [];
+    if (this.state !== "CLOSED") {
+      this.transitionTo("CLOSED");
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Internal
+  // ─────────────────────────────────────────────────────────────────────────
+  recordSuccess() {
+    this.consecutiveFailures = 0;
+    if (this.state === "HALF_OPEN") {
+      this.halfOpenSuccesses++;
+      if (this.halfOpenSuccesses >= this.successThreshold) {
+        this.transitionTo("CLOSED");
+      }
+    }
+  }
+  recordFailure(cause) {
+    this.consecutiveFailures++;
+    this.failureWindow.push(this.now());
+    this.pruneWindow();
+    if (this.state === "HALF_OPEN") {
+      this.transitionTo("OPEN", cause);
+      return;
+    }
+    if (this.state === "CLOSED" && this.failuresInCurrentWindow() >= this.failureThreshold) {
+      this.transitionTo("OPEN", cause);
+    }
+  }
+  transitionTo(to, cause) {
+    const from = this.state;
+    if (from === to) return;
+    this.state = to;
+    if (to === "OPEN") {
+      this.openedAt = this.now();
+      this.halfOpenSuccesses = 0;
+    } else if (to === "CLOSED") {
+      this.consecutiveFailures = 0;
+      this.halfOpenSuccesses = 0;
+      this.failureWindow = [];
+      this.openedAt = 0;
+    } else if (to === "HALF_OPEN") {
+      this.halfOpenSuccesses = 0;
+    }
+    this.onStateChange?.({
+      from,
+      to,
+      cause,
+      consecutiveFailures: this.consecutiveFailures
+    });
+  }
+  pruneWindow() {
+    const cutoff = this.now() - this.monitoringWindowMs;
+    while (this.failureWindow.length > 0 && this.failureWindow[0] < cutoff) {
+      this.failureWindow.shift();
+    }
+  }
+  failuresInCurrentWindow() {
+    this.pruneWindow();
+    return this.failureWindow.length;
+  }
+};
+
+export { CircuitBreaker, CircuitOpenError, InMemoryIdempotencyCache, InMemoryOAuthTokenStore, InMemoryStateAdapter, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, TEST_CARDS_AR, TEST_PAYERS_AR, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, computeMarketplaceFee, exchangeCodeForToken, expirationTimeMs, explainPaymentStatus, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map