@ar-agents/mercadopago 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,403 @@
+import { z } from 'zod';
+import { ToolSet } from 'ai';
+
+/**
+ * Base class for any error originating from the Mercado Pago integration. All
+ * specific error types extend this. Carries the MP HTTP status, the parsed
+ * body when available, and the endpoint that failed for debugging.
+ */
+declare class MercadoPagoError extends Error {
+    status: number;
+    endpoint: string;
+    mpResponse?: unknown | undefined;
+    constructor(message: string, status: number, endpoint: string, mpResponse?: unknown | undefined);
+}
+/**
+ * Thrown when the access token is missing, expired, or rejected by MP.
+ */
+declare class MercadoPagoAuthError extends MercadoPagoError {
+    constructor(endpoint: string, body?: unknown);
+}
+/**
+ * Thrown when MP returns the "back_url is not a valid URL" rejection. Common
+ * when devs pass localhost or http:// — MP requires HTTPS only, even in sandbox.
+ */
+declare class MercadoPagoBackUrlInvalidError extends MercadoPagoError {
+    constructor(endpoint: string, body?: unknown);
+}
+/**
+ * Thrown when the buyer email matches the seller account's email. MP refuses
+ * self-payment on subscriptions: the Confirmar button at the init_point UI
+ * stays disabled with no surfaceable error message.
+ */
+declare class MercadoPagoSelfPaymentError extends MercadoPagoError {
+    constructor(endpoint: string, body?: unknown);
+}
+/**
+ * Thrown when MP returns "Cannot operate between different countries". Despite
+ * the error text, this generally signals an account-type mismatch (real
+ * account-in-test-mode vs. test user account), not a literal country mismatch.
+ */
+declare class MercadoPagoAccountTypeMismatchError extends MercadoPagoError {
+    constructor(endpoint: string, body?: unknown);
+}
+/**
+ * Thrown when MP's risk engine rejects the first payment of a subscription.
+ * IMPORTANT: when this happens, MP automatically cancels the entire preapproval
+ * — you cannot retry on the same subscription, you must create a fresh one.
+ */
+declare class MercadoPagoPaymentRejectedError extends MercadoPagoError {
+    preapprovalId: string;
+    statusDetail: string | null;
+    constructor(preapprovalId: string, statusDetail: string | null, body?: unknown);
+}
+/**
+ * Thrown when an attempt is made to authorize a preapproval via API. Only the
+ * payer can authorize via the init_point UI; there is no admin override even
+ * in sandbox.
+ */
+declare class MercadoPagoAuthorizeForbiddenError extends MercadoPagoError {
+    constructor(preapprovalId: string, body?: unknown);
+}
+/**
+ * Thrown when MP rate-limits the integration. Retry with exponential backoff.
+ */
+declare class MercadoPagoRateLimitError extends MercadoPagoError {
+    retryAfterSeconds: number | null;
+    constructor(endpoint: string, retryAfterSeconds: number | null, body?: unknown);
+}
+/**
+ * Maps an MP error response body to the most specific known error class. Falls
+ * back to the generic MercadoPagoError when no specific pattern matches.
+ */
+declare function classifyError(status: number, endpoint: string, body: unknown, context?: {
+    preapprovalId?: string;
+    payerEmail?: string;
+    sellerEmail?: string;
+}): MercadoPagoError;
+
+/**
+ * Site IDs supported by Mercado Pago. The lib targets MLA (Argentina) primarily;
+ * other LATAM sites may work for the read paths but the full Subscriptions flow
+ * is only verified against MLA.
+ */
+declare const SiteIdSchema: z.ZodEnum<{
+    MLA: "MLA";
+    MLB: "MLB";
+    MLM: "MLM";
+    MCO: "MCO";
+    MLC: "MLC";
+    MLU: "MLU";
+}>;
+type SiteId = z.infer<typeof SiteIdSchema>;
+/**
+ * Currency identifiers MP exposes. ARS is the supported case for v0.1.
+ */
+declare const CurrencyIdSchema: z.ZodEnum<{
+    ARS: "ARS";
+    USD: "USD";
+    BRL: "BRL";
+    MXN: "MXN";
+}>;
+type CurrencyId = z.infer<typeof CurrencyIdSchema>;
+/**
+ * Recurrence frequency unit for a subscription's auto_recurring config.
+ */
+declare const FrequencyTypeSchema: z.ZodEnum<{
+    months: "months";
+    days: "days";
+}>;
+type FrequencyType = z.infer<typeof FrequencyTypeSchema>;
+/**
+ * Lifecycle states a Mercado Pago preapproval can be in. The string is the
+ * canonical MP value; we widen to `string` for forward compatibility because
+ * MP has historically introduced new states without notice.
+ */
+declare const PreapprovalStatusSchema: z.ZodUnion<readonly [z.ZodLiteral<"pending">, z.ZodLiteral<"authorized">, z.ZodLiteral<"paused">, z.ZodLiteral<"cancelled">, z.ZodString]>;
+type PreapprovalStatus = z.infer<typeof PreapprovalStatusSchema>;
+declare const AutoRecurringSchema: z.ZodObject<{
+    frequency: z.ZodNumber;
+    frequency_type: z.ZodEnum<{
+        months: "months";
+        days: "days";
+    }>;
+    transaction_amount: z.ZodNumber;
+    currency_id: z.ZodEnum<{
+        ARS: "ARS";
+        USD: "USD";
+        BRL: "BRL";
+        MXN: "MXN";
+    }>;
+    start_date: z.ZodOptional<z.ZodString>;
+    end_date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type AutoRecurring = z.infer<typeof AutoRecurringSchema>;
+declare const PreapprovalSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodUnion<readonly [z.ZodLiteral<"pending">, z.ZodLiteral<"authorized">, z.ZodLiteral<"paused">, z.ZodLiteral<"cancelled">, z.ZodString]>;
+    payer_email: z.ZodString;
+    init_point: z.ZodString;
+    external_reference: z.ZodOptional<z.ZodString>;
+    date_created: z.ZodString;
+    last_modified: z.ZodString;
+    next_payment_date: z.ZodOptional<z.ZodString>;
+    payer_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    auto_recurring: z.ZodObject<{
+        frequency: z.ZodNumber;
+        frequency_type: z.ZodEnum<{
+            months: "months";
+            days: "days";
+        }>;
+        transaction_amount: z.ZodNumber;
+        currency_id: z.ZodEnum<{
+            ARS: "ARS";
+            USD: "USD";
+            BRL: "BRL";
+            MXN: "MXN";
+        }>;
+        start_date: z.ZodOptional<z.ZodString>;
+        end_date: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type Preapproval = z.infer<typeof PreapprovalSchema>;
+/**
+ * Input for creating a preapproval (subscription). Internal field names match
+ * MP API semantics; the public client method maps from camelCase Naza-friendly
+ * params to the snake_case payload MP expects.
+ */
+interface CreatePreapprovalParams {
+    /** Short customer-facing description shown at checkout. */
+    reason: string;
+    /** Email of the buyer. Cannot equal the seller account's email (MP rejects). */
+    payerEmail: string;
+    /** Recurring amount per cycle. */
+    amount: number;
+    /** ARS for Argentina. Other currencies depend on the seller account's site. */
+    currency: CurrencyId;
+    /** Recurrence frequency (e.g., 1 + months = monthly). */
+    frequency: number;
+    frequencyType: FrequencyType;
+    /** HTTPS URL where MP redirects the buyer after first payment. localhost rejected. */
+    backUrl: string;
+    /** Optional client-side identifier for the subscription. */
+    externalReference?: string;
+}
+/**
+ * The shape of an MP webhook notification body for `topic=preapproval`. MP's
+ * webhook payload varies by event type; this is the union of fields seen in
+ * production.
+ */
+declare const WebhookBodySchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    topic: z.ZodOptional<z.ZodString>;
+    action: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodObject<{
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    }, z.core.$strip>>;
+    resource: z.ZodOptional<z.ZodString>;
+    user_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    api_version: z.ZodOptional<z.ZodString>;
+    date_created: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    live_mode: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+type WebhookBody = z.infer<typeof WebhookBodySchema>;
+/**
+ * Normalized webhook event after parsing. The library extracts topic + dataId
+ * from either query params or body, since MP sends them in either location
+ * depending on integration version.
+ */
+interface ParsedWebhookEvent {
+    /** Topic of the event, e.g., "preapproval", "payment", "subscription_authorized_payment". */
+    topic: string;
+    /** ID of the affected resource. */
+    dataId: string;
+    /** Action descriptor when present (e.g., "updated", "created"). */
+    action: string | null;
+    /** Raw body MP sent, for caller inspection / debugging. */
+    raw: WebhookBody;
+}
+
+interface MercadoPagoClientOptions {
+    /** Access token. TEST- prefix for sandbox, APP_USR- for production. */
+    accessToken: string;
+    /**
+     * Override the API base URL. Mostly useful for tests against MSW or for
+     * pointing at a regional MP host. Defaults to https://api.mercadopago.com.
+     */
+    baseUrl?: string;
+    /**
+     * Custom fetch implementation. Defaults to globalThis.fetch. Override to
+     * inject your own retry/instrumentation layer or to test with MSW.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Thin, typed wrapper around Mercado Pago's REST API. Only the endpoints the
+ * agent layer needs are exposed; this is deliberately narrow rather than a
+ * full SDK rebuild.
+ */
+declare class MercadoPagoClient {
+    private readonly accessToken;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: MercadoPagoClientOptions);
+    private request;
+    /**
+     * Create a recurring subscription (preapproval). The returned `init_point`
+     * URL is where the buyer must complete the FIRST payment with their card +
+     * CVV — there is no API path that bypasses this human step.
+     */
+    createPreapproval(params: CreatePreapprovalParams): Promise<Preapproval>;
+    /**
+     * Fetch the current state of a preapproval. Useful to confirm whether the
+     * buyer has completed the first payment (`status: 'authorized'`) or whether
+     * the subscription was cancelled.
+     */
+    getPreapproval(id: string): Promise<Preapproval>;
+    /**
+     * Cancel an active preapproval. Irreversible: MP will not charge the buyer
+     * again and the subscription cannot be reactivated.
+     */
+    cancelPreapproval(id: string): Promise<Preapproval>;
+    /**
+     * Pause an authorized preapproval. The subscription stops auto-charging but
+     * can be re-activated. Note: MP only allows pausing subs that are currently
+     * `authorized` — pending/cancelled subs reject this.
+     */
+    pausePreapproval(id: string): Promise<Preapproval>;
+    /**
+     * Re-activate a paused preapproval. Charges resume on the next scheduled
+     * date.
+     */
+    resumePreapproval(id: string): Promise<Preapproval>;
+}
+
+/**
+ * In-memory record of a subscription. The lib persists the MP-side fields
+ * needed to reason about a subscription without hitting the API every time
+ * (status, last webhook info, customer email, etc.) plus a free-form metadata
+ * bag for callers to attach business context (tenant id, plan name, etc.).
+ */
+interface SubscriptionStateRecord {
+    status?: string;
+    payerEmail?: string;
+    amount?: number;
+    currency?: string;
+    frequency?: number;
+    frequencyType?: string;
+    initPoint?: string;
+    externalReference?: string;
+    createdAt?: string;
+    cancelledAt?: string;
+    lastWebhookStatus?: string;
+    lastWebhookAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Persistence surface for subscription state. Implementations may back this
+ * with Upstash Redis, Vercel KV, Postgres, in-memory, or anything that
+ * supports the three operations. The default `InMemoryStateAdapter` is
+ * provided for tests and trivial single-process deployments; production
+ * setups should plug in a durable store.
+ */
+interface SubscriptionStateAdapter {
+    set(id: string, state: Partial<SubscriptionStateRecord>): Promise<void>;
+    get(id: string): Promise<SubscriptionStateRecord | null>;
+    list?(): Promise<string[]>;
+}
+/**
+ * Volatile, single-process state adapter. Useful for tests and demos. Do not
+ * use in production: state is lost on restart and is not safe across tenants.
+ */
+declare class InMemoryStateAdapter implements SubscriptionStateAdapter {
+    private readonly store;
+    set(id: string, state: Partial<SubscriptionStateRecord>): Promise<void>;
+    get(id: string): Promise<SubscriptionStateRecord | null>;
+    list(): Promise<string[]>;
+    /** Test helper: drop everything. Not part of the adapter interface. */
+    reset(): void;
+}
+
+interface MercadoPagoToolsOptions {
+    /** State adapter for persisting subscription records. */
+    state: SubscriptionStateAdapter;
+    /**
+     * Default back_url used when callers don't supply one. MUST be HTTPS — MP
+     * rejects http:// and localhost back URLs even in sandbox.
+     */
+    backUrl: string;
+    /**
+     * Optionally override the agent-facing tool descriptions. Pass an object
+     * with keys matching tool names; values replace the default description.
+     * Useful for localizing the agent's tool reasoning.
+     */
+    descriptions?: Partial<Record<ToolName, string>>;
+}
+type ToolName = "create_subscription" | "get_subscription_status" | "cancel_subscription" | "pause_subscription" | "resume_subscription";
+/**
+ * Build a tool set for the Vercel AI SDK that exposes Mercado Pago Subscriptions
+ * to an agent. Pass directly to `Experimental_Agent`'s `tools` option, or merge
+ * with other tool sets.
+ *
+ * @example
+ * ```ts
+ * import { Experimental_Agent as Agent, stepCountIs } from 'ai';
+ * import { MercadoPagoClient, mercadoPagoTools, InMemoryStateAdapter } from '@ar-agents/mercadopago';
+ *
+ * const mp = new MercadoPagoClient({ accessToken: process.env.MP_ACCESS_TOKEN! });
+ * const agent = new Agent({
+ *   model: 'anthropic/claude-sonnet-4-6',
+ *   tools: mercadoPagoTools(mp, {
+ *     state: new InMemoryStateAdapter(),
+ *     backUrl: 'https://mysite.com/done',
+ *   }),
+ *   stopWhen: stepCountIs(8),
+ * });
+ * ```
+ */
+declare function mercadoPagoTools(client: MercadoPagoClient, options: MercadoPagoToolsOptions): ToolSet;
+
+/**
+ * Parse a Mercado Pago webhook from the raw request body and URL search params.
+ * MP sends the topic and resource id in EITHER the URL query string OR the
+ * body, depending on integration version — this normalizes both shapes into a
+ * single structure.
+ *
+ * @example
+ * ```ts
+ * export async function POST(req: Request) {
+ *   const body = await req.json().catch(() => ({}));
+ *   const event = parseWebhookEvent(body, new URL(req.url).searchParams);
+ *   if (event && event.topic === 'preapproval') {
+ *     // refresh status from MP, update your store
+ *   }
+ *   return Response.json({ received: true });
+ * }
+ * ```
+ */
+declare function parseWebhookEvent(body: unknown, searchParams?: URLSearchParams): ParsedWebhookEvent | null;
+/**
+ * Verify the HMAC-SHA256 signature MP sends in the `x-signature` header for
+ * webhook authenticity. Returns true if the signature matches the expected
+ * value derived from the integration's secret key.
+ *
+ * @param requestId The value of the `x-request-id` request header.
+ * @param dataId The id of the resource the webhook is about (from query or body).
+ * @param signatureHeader The full `x-signature` header value MP sent.
+ * @param secret Your integration's webhook secret (configured in MP dev panel).
+ *
+ * @remarks
+ * MP's `x-signature` header has the form: `ts=NNNNNNNN,v1=HEXSIGNATURE`. We
+ * extract the timestamp and the v1 signature, then compute
+ * `HMAC-SHA256(secret, "id:${dataId};request-id:${requestId};ts:${ts};")`
+ * and compare with constant-time equality.
+ */
+declare function verifyWebhookSignature(params: {
+    requestId: string | null;
+    dataId: string;
+    signatureHeader: string | null;
+    secret: string;
+}): boolean;
+
+export { type AutoRecurring, type CreatePreapprovalParams, type CurrencyId, type FrequencyType, InMemoryStateAdapter, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, type MercadoPagoToolsOptions, type ParsedWebhookEvent, type Preapproval, type PreapprovalStatus, type SiteId, type SubscriptionStateAdapter, type SubscriptionStateRecord, type WebhookBody, classifyError, mercadoPagoTools, parseWebhookEvent, verifyWebhookSignature };