@devly-cl/mercadopago-client

CommonJS TypeScript package for the Mercado Pago protocol currently used by the host. Requires Node 24. No runtime dependencies, Nest, TypeORM, Axios, configuration environment access, entitlement model or SaaS provider capabilities.

Install

npm install @devly-cl/mercadopago-client

Public API

Runtime exports: MercadoPagoHttpClient, MercadoPagoClientError, findApprovedPaymentReference. Request, response, credential, transport and evidence types are explicit exports. Declaration consumers use NodeNext, types: [] and lib: ["ES2023"]; no DOM or Node type dependency is exposed.

const client = new MercadoPagoHttpClient({
  getCredentials: () => ({ accessToken: secretStore.currentToken() }),
  apiBaseUrl: 'https://api.mercadopago.com',
  timeoutMs: 10_000,
});
await client.getPreapproval('opaque-provider-id');

The client provides createPreapprovalPlan(input, key), createPreapproval(input, key), getPreapproval(id), updatePreapproval(id, input, key) and searchPayments(query). Inputs use wire vocabulary; product names, commercial IDs, amounts and return URLs are supplied by the host. updatePreapproval returns an uninterpreted body (parsed JSON, text or undefined for an empty acknowledgement): the host decides which response evidence is required for its action.

Credentials are read per request. Options retain their original object and method receivers, including prototype methods and transport getters. The optional structural transport receives { method, url, headers, body?, timeoutMs } and returns { status, body }. The default transport uses native fetch, rejects redirects and aborts after the timeout; injected transports must honor the supplied timeout for their own resource cleanup. The client bounds their awaited result but cannot cancel external effects or an injected transport that ignores the deadline.

The base URL is configurable HTTPS, without embedded user/password. The default timeout is 10 seconds. Requests preserve Bearer authorization, JSON for mutations, X-Idempotency-Key, escaped opaque IDs and the approved-payment query ordering. Searches accept a bounded limit; the existing host continues to request 20 records. Construction performs no I/O.

Errors and evidence

MercadoPagoClientError contains only a fixed message, own code, uncertain, retryable and optional httpStatus. Codes are INVALID_CONFIGURATION, INVALID_REQUEST, TRANSPORT_FAILURE, TIMEOUT, HTTP_ERROR and INVALID_RESPONSE. It carries no response body, token, URL or transport cause. Credential-provider exceptions occur before dispatch and retain their identity.

Each method makes one request and never retries automatically. Transport loss, timeout and HTTP 408/409/429/5xx are retryable conditions; mutations in those cases are uncertain. Failed validation of a successful create response is also uncertain. GET failures cannot themselves imply a remote mutation. retryable describes the failure class, not permission to replay a mutation: callers must consider uncertainty and their own durable recovery contract.

findApprovedPaymentReference(response, expected) checks approved status, payment ID, external reference, preapproval ID, collector, exact safe integer CLP amount and currency. It returns an opaque payment reference or null. It never activates access or writes financial state. Subscription status and browser return are not payment evidence.

Host responsibilities

The integrating application owns configuration flags and secrets, capability selection, commercial rules, CLP/tax/proration, billing day, validity, return URLs, immutable quotes, tenant/RBAC, database operations, leases, retry scheduling, audit and notifications. This client exposes no webhook endpoint and does not activate access.

An add-on checkout can require two independent provider POSTs: one plan, then one preapproval. Idempotency keys are request metadata; they do not make that sequence atomic or prove that a lost response had no remote effect. A production host must persist the operation, immutable request fingerprint, plan checkpoint and preapproval checkpoint around each provider step. When the result of a submitted request is unknown, recover with an authorized canonical provider read where possible; otherwise route the operation to audited manual review. Do not replay a possibly dispatched POST solely because its transport failed.

Before a host treats a preapproval or cancellation as a local state change, it must verify canonical ownership and state: the requested provider ID, collector, external reference, expected plan association and final subscription status. A browser return or a 2xx cancellation acknowledgement is not payment or cancellation evidence. Price-change and approved-payment evidence checks remain host responsibilities.

Verification

Tests use intercepted transports and synthetic credentials. The isolated tarball consumer installs only this package offline and verifies operations, errors, evidence and CJS/ESM/NodeNext declarations. These tests establish local compatibility, not a real Mercado Pago transaction, production readiness of credentials or browser QA.

Build from the root with npm run build:packages; then run this workspace's tests or npm run test:package-artifacts. Package source changes require rebuilding before starting the host; automatic package hot reload is not provided.