@ar-agents/mercadopago 0.7.0 → 0.9.0

package/dist/state-C6Wzb_XX.d.cts

@@ -0,0 +1,106 @@
+/**
+ * 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 OAuthTokenRecord {
+    user_id: string;
+    access_token: string;
+    refresh_token: string;
+    /** Unix-ms timestamp when access_token expires. */
+    expires_at: number;
+    /** OAuth scope granted, if any. */
+    scope?: string;
+    /** Optional: any business metadata you want to attach (tenant id, etc.). */
+    metadata?: Record<string, unknown>;
+}
+interface OAuthTokenStore {
+    /** Persist (or update) the token for `user_id`. */
+    set(userId: string, token: OAuthTokenRecord): Promise<void>;
+    /** Fetch the stored token, or null if no token registered for that seller. */
+    get(userId: string): Promise<OAuthTokenRecord | null>;
+    /** Forget a seller's token (e.g., they revoked the app). */
+    delete(userId: string): Promise<void>;
+    /** Optional: enumerate all sellers (useful for batch refresh jobs). */
+    list?(): Promise<string[]>;
+}
+/**
+ * Volatile, single-process OAuth token store. NOT for production marketplace
+ * setups — tokens are lost on restart. Plug in `VercelKVOAuthTokenStore`
+ * (from `@ar-agents/mercadopago/vercel-kv`) or your own Postgres-backed
+ * implementation.
+ */
+declare class InMemoryOAuthTokenStore implements OAuthTokenStore {
+    private readonly store;
+    set(userId: string, token: OAuthTokenRecord): Promise<void>;
+    get(userId: string): Promise<OAuthTokenRecord | null>;
+    delete(userId: string): Promise<void>;
+    list(): Promise<string[]>;
+    /** Test helper. */
+    reset(): void;
+}
+interface IdempotencyCache {
+    /** Get the cached response for a key, or null if not present / expired. */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Store a response under `key`. `ttlSeconds` defaults to 24h — match MP's
+     * own idempotency window so the cache becomes irrelevant once MP would
+     * forget anyway.
+     */
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /** Forget a cache entry (force a re-fetch on next call). */
+    delete(key: string): Promise<void>;
+}
+/**
+ * Volatile, single-process idempotency cache. Tests + dev only.
+ */
+declare class InMemoryIdempotencyCache implements IdempotencyCache {
+    private readonly store;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Test helper. */
+    reset(): void;
+}
+
+export { type IdempotencyCache as I, type OAuthTokenRecord as O, type SubscriptionStateAdapter as S, InMemoryIdempotencyCache as a, InMemoryOAuthTokenStore as b, InMemoryStateAdapter as c, type OAuthTokenStore as d, type SubscriptionStateRecord as e };

package/dist/state-C6Wzb_XX.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 OAuthTokenRecord {
+    user_id: string;
+    access_token: string;
+    refresh_token: string;
+    /** Unix-ms timestamp when access_token expires. */
+    expires_at: number;
+    /** OAuth scope granted, if any. */
+    scope?: string;
+    /** Optional: any business metadata you want to attach (tenant id, etc.). */
+    metadata?: Record<string, unknown>;
+}
+interface OAuthTokenStore {
+    /** Persist (or update) the token for `user_id`. */
+    set(userId: string, token: OAuthTokenRecord): Promise<void>;
+    /** Fetch the stored token, or null if no token registered for that seller. */
+    get(userId: string): Promise<OAuthTokenRecord | null>;
+    /** Forget a seller's token (e.g., they revoked the app). */
+    delete(userId: string): Promise<void>;
+    /** Optional: enumerate all sellers (useful for batch refresh jobs). */
+    list?(): Promise<string[]>;
+}
+/**
+ * Volatile, single-process OAuth token store. NOT for production marketplace
+ * setups — tokens are lost on restart. Plug in `VercelKVOAuthTokenStore`
+ * (from `@ar-agents/mercadopago/vercel-kv`) or your own Postgres-backed
+ * implementation.
+ */
+declare class InMemoryOAuthTokenStore implements OAuthTokenStore {
+    private readonly store;
+    set(userId: string, token: OAuthTokenRecord): Promise<void>;
+    get(userId: string): Promise<OAuthTokenRecord | null>;
+    delete(userId: string): Promise<void>;
+    list(): Promise<string[]>;
+    /** Test helper. */
+    reset(): void;
+}
+interface IdempotencyCache {
+    /** Get the cached response for a key, or null if not present / expired. */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Store a response under `key`. `ttlSeconds` defaults to 24h — match MP's
+     * own idempotency window so the cache becomes irrelevant once MP would
+     * forget anyway.
+     */
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /** Forget a cache entry (force a re-fetch on next call). */
+    delete(key: string): Promise<void>;
+}
+/**
+ * Volatile, single-process idempotency cache. Tests + dev only.
+ */
+declare class InMemoryIdempotencyCache implements IdempotencyCache {
+    private readonly store;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Test helper. */
+    reset(): void;
+}
+
+export { type IdempotencyCache as I, type OAuthTokenRecord as O, type SubscriptionStateAdapter as S, InMemoryIdempotencyCache as a, InMemoryOAuthTokenStore as b, InMemoryStateAdapter as c, type OAuthTokenStore as d, type SubscriptionStateRecord as e };

package/dist/vercel-kv.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+var kv = require('@vercel/kv');
+
+// src/vercel-kv.ts
+var DEFAULT_SUBSCRIPTION_PREFIX = "mp:sub:";
+var DEFAULT_OAUTH_PREFIX = "mp:oauth:";
+var DEFAULT_IDEMPOTENCY_PREFIX = "mp:idem:";
+var VercelKVSubscriptionStateAdapter = class {
+  kv;
+  prefix;
+  indexKey;
+  constructor(options = {}) {
+    this.kv = options.kv ?? kv.kv;
+    this.prefix = options.prefix ?? DEFAULT_SUBSCRIPTION_PREFIX;
+    this.indexKey = `${this.prefix}__index`;
+  }
+  key(id) {
+    return `${this.prefix}${id}`;
+  }
+  async set(id, state) {
+    const existing = await this.kv.get(this.key(id)) ?? {};
+    await this.kv.set(this.key(id), { ...existing, ...state });
+    await this.kv.sadd(this.indexKey, id);
+  }
+  async get(id) {
+    return await this.kv.get(this.key(id)) ?? null;
+  }
+  async list() {
+    const ids = await this.kv.smembers(this.indexKey);
+    return ids.map(String);
+  }
+  /** Forget a subscription record. NOT part of the adapter interface. */
+  async delete(id) {
+    await this.kv.del(this.key(id));
+    await this.kv.srem(this.indexKey, id);
+  }
+};
+var VercelKVOAuthTokenStore = class {
+  kv;
+  prefix;
+  indexKey;
+  constructor(options = {}) {
+    this.kv = options.kv ?? kv.kv;
+    this.prefix = options.prefix ?? DEFAULT_OAUTH_PREFIX;
+    this.indexKey = `${this.prefix}__index`;
+  }
+  key(userId) {
+    return `${this.prefix}${userId}`;
+  }
+  async set(userId, token) {
+    await this.kv.set(this.key(userId), token);
+    await this.kv.sadd(this.indexKey, userId);
+  }
+  async get(userId) {
+    return await this.kv.get(this.key(userId)) ?? null;
+  }
+  async delete(userId) {
+    await this.kv.del(this.key(userId));
+    await this.kv.srem(this.indexKey, userId);
+  }
+  async list() {
+    const ids = await this.kv.smembers(this.indexKey);
+    return ids.map(String);
+  }
+};
+var VercelKVIdempotencyCache = class {
+  kv;
+  prefix;
+  constructor(options = {}) {
+    this.kv = options.kv ?? kv.kv;
+    this.prefix = options.prefix ?? DEFAULT_IDEMPOTENCY_PREFIX;
+  }
+  key(k) {
+    return `${this.prefix}${k}`;
+  }
+  async get(key) {
+    return await this.kv.get(this.key(key)) ?? null;
+  }
+  async set(key, value, ttlSeconds = 86400) {
+    await this.kv.set(this.key(key), value, { ex: ttlSeconds });
+  }
+  async delete(key) {
+    await this.kv.del(this.key(key));
+  }
+};
+
+exports.VercelKVIdempotencyCache = VercelKVIdempotencyCache;
+exports.VercelKVOAuthTokenStore = VercelKVOAuthTokenStore;
+exports.VercelKVSubscriptionStateAdapter = VercelKVSubscriptionStateAdapter;
+//# sourceMappingURL=vercel-kv.cjs.map
+//# sourceMappingURL=vercel-kv.cjs.map

package/dist/vercel-kv.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vercel-kv.ts"],"names":["defaultKv"],"mappings":"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","file":"vercel-kv.cjs","sourcesContent":["/**\n * Vercel KV adapters — drop-in `SubscriptionStateAdapter`,\n * `OAuthTokenStore`, and `IdempotencyCache` implementations backed by\n * [Vercel KV](https://vercel.com/docs/storage/vercel-kv) (Upstash Redis).\n *\n * # Why a separate subpath?\n *\n * `@vercel/kv` is a peer dependency — only consumers who actually use Vercel\n * KV install it. Importing from `@ar-agents/mercadopago/vercel-kv` is\n * lazy: the main `@ar-agents/mercadopago` bundle stays tiny for callers who\n * use the in-memory adapters or a different store.\n *\n * # Setup\n *\n * 1. Create a KV store at https://vercel.com/dashboard/stores\n * 2. Connect it to your project — Vercel auto-injects `KV_*` env vars\n * 3. `pnpm add @vercel/kv`\n * 4. Wire the adapters:\n *\n *    ```ts\n *    import { mercadoPagoTools, MercadoPagoClient } from \"@ar-agents/mercadopago\";\n *    import {\n *      VercelKVSubscriptionStateAdapter,\n *      VercelKVOAuthTokenStore,\n *    } from \"@ar-agents/mercadopago/vercel-kv\";\n *\n *    const tools = mercadoPagoTools(client, {\n *      state: new VercelKVSubscriptionStateAdapter(),\n *      backUrl: \"https://mysite.com/done\",\n *      // ... oauth, webhookSecret, etc.\n *    });\n *\n *    // For marketplace flows, also wire the OAuth token store:\n *    const oauthStore = new VercelKVOAuthTokenStore();\n *    await oauthStore.set(token.user_id, {\n *      user_id: token.user_id,\n *      access_token: token.access_token,\n *      refresh_token: token.refresh_token!,\n *      expires_at: Date.now() + (token.expires_in ?? 21600) * 1000,\n *    });\n *    ```\n *\n * # Edge Runtime\n *\n * `@vercel/kv` works in Vercel Edge Runtime, Node.js, and any environment\n * with `fetch` (it's a thin REST client over Upstash). All adapters here\n * are async and Edge-safe.\n *\n * # Key namespacing\n *\n * Each adapter uses its own prefix so multiple adapters can share the same\n * KV store without collisions:\n * - Subscriptions: `mp:sub:{id}`\n * - OAuth tokens:  `mp:oauth:{userId}`\n * - Idempotency:   `mp:idem:{key}`\n *\n * Pass a custom prefix via the constructor if you need to share the store\n * with other apps.\n */\n\nimport { kv as defaultKv } from \"@vercel/kv\";\nimport type { VercelKV } from \"@vercel/kv\";\nimport type {\n  IdempotencyCache,\n  OAuthTokenRecord,\n  OAuthTokenStore,\n  SubscriptionStateAdapter,\n  SubscriptionStateRecord,\n} from \"./state\";\n\nconst DEFAULT_SUBSCRIPTION_PREFIX = \"mp:sub:\";\nconst DEFAULT_OAUTH_PREFIX = \"mp:oauth:\";\nconst DEFAULT_IDEMPOTENCY_PREFIX = \"mp:idem:\";\n\ninterface VercelKVAdapterOptions {\n  /**\n   * Custom KV client. If omitted, uses the default `kv` export from\n   * `@vercel/kv` (which reads `KV_REST_API_URL` + `KV_REST_API_TOKEN` from\n   * env — auto-injected when you connect a KV store to your Vercel project).\n   */\n  kv?: VercelKV;\n  /** Override the key prefix. */\n  prefix?: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// SubscriptionStateAdapter\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport class VercelKVSubscriptionStateAdapter\n  implements SubscriptionStateAdapter\n{\n  private readonly kv: VercelKV;\n  private readonly prefix: string;\n  private readonly indexKey: string;\n\n  constructor(options: VercelKVAdapterOptions = {}) {\n    this.kv = options.kv ?? defaultKv;\n    this.prefix = options.prefix ?? DEFAULT_SUBSCRIPTION_PREFIX;\n    this.indexKey = `${this.prefix}__index`;\n  }\n\n  private key(id: string): string {\n    return `${this.prefix}${id}`;\n  }\n\n  async set(\n    id: string,\n    state: Partial<SubscriptionStateRecord>,\n  ): Promise<void> {\n    const existing = (await this.kv.get<SubscriptionStateRecord>(this.key(id))) ?? {};\n    await this.kv.set(this.key(id), { ...existing, ...state });\n    await this.kv.sadd(this.indexKey, id);\n  }\n\n  async get(id: string): Promise<SubscriptionStateRecord | null> {\n    return (await this.kv.get<SubscriptionStateRecord>(this.key(id))) ?? null;\n  }\n\n  async list(): Promise<string[]> {\n    const ids = await this.kv.smembers(this.indexKey);\n    return ids.map(String);\n  }\n\n  /** Forget a subscription record. NOT part of the adapter interface. */\n  async delete(id: string): Promise<void> {\n    await this.kv.del(this.key(id));\n    await this.kv.srem(this.indexKey, id);\n  }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// OAuthTokenStore (per-seller marketplace token persistence)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport class VercelKVOAuthTokenStore implements OAuthTokenStore {\n  private readonly kv: VercelKV;\n  private readonly prefix: string;\n  private readonly indexKey: string;\n\n  constructor(options: VercelKVAdapterOptions = {}) {\n    this.kv = options.kv ?? defaultKv;\n    this.prefix = options.prefix ?? DEFAULT_OAUTH_PREFIX;\n    this.indexKey = `${this.prefix}__index`;\n  }\n\n  private key(userId: string): string {\n    return `${this.prefix}${userId}`;\n  }\n\n  async set(userId: string, token: OAuthTokenRecord): Promise<void> {\n    await this.kv.set(this.key(userId), token);\n    await this.kv.sadd(this.indexKey, userId);\n  }\n\n  async get(userId: string): Promise<OAuthTokenRecord | null> {\n    return (await this.kv.get<OAuthTokenRecord>(this.key(userId))) ?? null;\n  }\n\n  async delete(userId: string): Promise<void> {\n    await this.kv.del(this.key(userId));\n    await this.kv.srem(this.indexKey, userId);\n  }\n\n  async list(): Promise<string[]> {\n    const ids = await this.kv.smembers(this.indexKey);\n    return ids.map(String);\n  }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// IdempotencyCache (KV-backed dedup of agent retries)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport class VercelKVIdempotencyCache implements IdempotencyCache {\n  private readonly kv: VercelKV;\n  private readonly prefix: string;\n\n  constructor(options: VercelKVAdapterOptions = {}) {\n    this.kv = options.kv ?? defaultKv;\n    this.prefix = options.prefix ?? DEFAULT_IDEMPOTENCY_PREFIX;\n  }\n\n  private key(k: string): string {\n    return `${this.prefix}${k}`;\n  }\n\n  async get<T>(key: string): Promise<T | null> {\n    return (await this.kv.get<T>(this.key(key))) ?? null;\n  }\n\n  async set<T>(key: string, value: T, ttlSeconds = 86_400): Promise<void> {\n    // Vercel KV's `set` supports a TTL in seconds via the `ex` option.\n    await this.kv.set(this.key(key), value, { ex: ttlSeconds });\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.kv.del(this.key(key));\n  }\n}\n"]}

package/dist/vercel-kv.d.cts

@@ -0,0 +1,107 @@
+import { VercelKV } from '@vercel/kv';
+import { I as IdempotencyCache, d as OAuthTokenStore, O as OAuthTokenRecord, S as SubscriptionStateAdapter, e as SubscriptionStateRecord } from './state-C6Wzb_XX.cjs';
+
+/**
+ * Vercel KV adapters — drop-in `SubscriptionStateAdapter`,
+ * `OAuthTokenStore`, and `IdempotencyCache` implementations backed by
+ * [Vercel KV](https://vercel.com/docs/storage/vercel-kv) (Upstash Redis).
+ *
+ * # Why a separate subpath?
+ *
+ * `@vercel/kv` is a peer dependency — only consumers who actually use Vercel
+ * KV install it. Importing from `@ar-agents/mercadopago/vercel-kv` is
+ * lazy: the main `@ar-agents/mercadopago` bundle stays tiny for callers who
+ * use the in-memory adapters or a different store.
+ *
+ * # Setup
+ *
+ * 1. Create a KV store at https://vercel.com/dashboard/stores
+ * 2. Connect it to your project — Vercel auto-injects `KV_*` env vars
+ * 3. `pnpm add @vercel/kv`
+ * 4. Wire the adapters:
+ *
+ *    ```ts
+ *    import { mercadoPagoTools, MercadoPagoClient } from "@ar-agents/mercadopago";
+ *    import {
+ *      VercelKVSubscriptionStateAdapter,
+ *      VercelKVOAuthTokenStore,
+ *    } from "@ar-agents/mercadopago/vercel-kv";
+ *
+ *    const tools = mercadoPagoTools(client, {
+ *      state: new VercelKVSubscriptionStateAdapter(),
+ *      backUrl: "https://mysite.com/done",
+ *      // ... oauth, webhookSecret, etc.
+ *    });
+ *
+ *    // For marketplace flows, also wire the OAuth token store:
+ *    const oauthStore = new VercelKVOAuthTokenStore();
+ *    await oauthStore.set(token.user_id, {
+ *      user_id: token.user_id,
+ *      access_token: token.access_token,
+ *      refresh_token: token.refresh_token!,
+ *      expires_at: Date.now() + (token.expires_in ?? 21600) * 1000,
+ *    });
+ *    ```
+ *
+ * # Edge Runtime
+ *
+ * `@vercel/kv` works in Vercel Edge Runtime, Node.js, and any environment
+ * with `fetch` (it's a thin REST client over Upstash). All adapters here
+ * are async and Edge-safe.
+ *
+ * # Key namespacing
+ *
+ * Each adapter uses its own prefix so multiple adapters can share the same
+ * KV store without collisions:
+ * - Subscriptions: `mp:sub:{id}`
+ * - OAuth tokens:  `mp:oauth:{userId}`
+ * - Idempotency:   `mp:idem:{key}`
+ *
+ * Pass a custom prefix via the constructor if you need to share the store
+ * with other apps.
+ */
+
+interface VercelKVAdapterOptions {
+    /**
+     * Custom KV client. If omitted, uses the default `kv` export from
+     * `@vercel/kv` (which reads `KV_REST_API_URL` + `KV_REST_API_TOKEN` from
+     * env — auto-injected when you connect a KV store to your Vercel project).
+     */
+    kv?: VercelKV;
+    /** Override the key prefix. */
+    prefix?: string;
+}
+declare class VercelKVSubscriptionStateAdapter implements SubscriptionStateAdapter {
+    private readonly kv;
+    private readonly prefix;
+    private readonly indexKey;
+    constructor(options?: VercelKVAdapterOptions);
+    private key;
+    set(id: string, state: Partial<SubscriptionStateRecord>): Promise<void>;
+    get(id: string): Promise<SubscriptionStateRecord | null>;
+    list(): Promise<string[]>;
+    /** Forget a subscription record. NOT part of the adapter interface. */
+    delete(id: string): Promise<void>;
+}
+declare class VercelKVOAuthTokenStore implements OAuthTokenStore {
+    private readonly kv;
+    private readonly prefix;
+    private readonly indexKey;
+    constructor(options?: VercelKVAdapterOptions);
+    private key;
+    set(userId: string, token: OAuthTokenRecord): Promise<void>;
+    get(userId: string): Promise<OAuthTokenRecord | null>;
+    delete(userId: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+declare class VercelKVIdempotencyCache implements IdempotencyCache {
+    private readonly kv;
+    private readonly prefix;
+    constructor(options?: VercelKVAdapterOptions);
+    private key;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+
+export { VercelKVIdempotencyCache, VercelKVOAuthTokenStore, VercelKVSubscriptionStateAdapter };

package/dist/vercel-kv.d.ts

@@ -0,0 +1,107 @@
+import { VercelKV } from '@vercel/kv';
+import { I as IdempotencyCache, d as OAuthTokenStore, O as OAuthTokenRecord, S as SubscriptionStateAdapter, e as SubscriptionStateRecord } from './state-C6Wzb_XX.js';
+
+/**
+ * Vercel KV adapters — drop-in `SubscriptionStateAdapter`,
+ * `OAuthTokenStore`, and `IdempotencyCache` implementations backed by
+ * [Vercel KV](https://vercel.com/docs/storage/vercel-kv) (Upstash Redis).
+ *
+ * # Why a separate subpath?
+ *
+ * `@vercel/kv` is a peer dependency — only consumers who actually use Vercel
+ * KV install it. Importing from `@ar-agents/mercadopago/vercel-kv` is
+ * lazy: the main `@ar-agents/mercadopago` bundle stays tiny for callers who
+ * use the in-memory adapters or a different store.
+ *
+ * # Setup
+ *
+ * 1. Create a KV store at https://vercel.com/dashboard/stores
+ * 2. Connect it to your project — Vercel auto-injects `KV_*` env vars
+ * 3. `pnpm add @vercel/kv`
+ * 4. Wire the adapters:
+ *
+ *    ```ts
+ *    import { mercadoPagoTools, MercadoPagoClient } from "@ar-agents/mercadopago";
+ *    import {
+ *      VercelKVSubscriptionStateAdapter,
+ *      VercelKVOAuthTokenStore,
+ *    } from "@ar-agents/mercadopago/vercel-kv";
+ *
+ *    const tools = mercadoPagoTools(client, {
+ *      state: new VercelKVSubscriptionStateAdapter(),
+ *      backUrl: "https://mysite.com/done",
+ *      // ... oauth, webhookSecret, etc.
+ *    });
+ *
+ *    // For marketplace flows, also wire the OAuth token store:
+ *    const oauthStore = new VercelKVOAuthTokenStore();
+ *    await oauthStore.set(token.user_id, {
+ *      user_id: token.user_id,
+ *      access_token: token.access_token,
+ *      refresh_token: token.refresh_token!,
+ *      expires_at: Date.now() + (token.expires_in ?? 21600) * 1000,
+ *    });
+ *    ```
+ *
+ * # Edge Runtime
+ *
+ * `@vercel/kv` works in Vercel Edge Runtime, Node.js, and any environment
+ * with `fetch` (it's a thin REST client over Upstash). All adapters here
+ * are async and Edge-safe.
+ *
+ * # Key namespacing
+ *
+ * Each adapter uses its own prefix so multiple adapters can share the same
+ * KV store without collisions:
+ * - Subscriptions: `mp:sub:{id}`
+ * - OAuth tokens:  `mp:oauth:{userId}`
+ * - Idempotency:   `mp:idem:{key}`
+ *
+ * Pass a custom prefix via the constructor if you need to share the store
+ * with other apps.
+ */
+
+interface VercelKVAdapterOptions {
+    /**
+     * Custom KV client. If omitted, uses the default `kv` export from
+     * `@vercel/kv` (which reads `KV_REST_API_URL` + `KV_REST_API_TOKEN` from
+     * env — auto-injected when you connect a KV store to your Vercel project).
+     */
+    kv?: VercelKV;
+    /** Override the key prefix. */
+    prefix?: string;
+}
+declare class VercelKVSubscriptionStateAdapter implements SubscriptionStateAdapter {
+    private readonly kv;
+    private readonly prefix;
+    private readonly indexKey;
+    constructor(options?: VercelKVAdapterOptions);
+    private key;
+    set(id: string, state: Partial<SubscriptionStateRecord>): Promise<void>;
+    get(id: string): Promise<SubscriptionStateRecord | null>;
+    list(): Promise<string[]>;
+    /** Forget a subscription record. NOT part of the adapter interface. */
+    delete(id: string): Promise<void>;
+}
+declare class VercelKVOAuthTokenStore implements OAuthTokenStore {
+    private readonly kv;
+    private readonly prefix;
+    private readonly indexKey;
+    constructor(options?: VercelKVAdapterOptions);
+    private key;
+    set(userId: string, token: OAuthTokenRecord): Promise<void>;
+    get(userId: string): Promise<OAuthTokenRecord | null>;
+    delete(userId: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+declare class VercelKVIdempotencyCache implements IdempotencyCache {
+    private readonly kv;
+    private readonly prefix;
+    constructor(options?: VercelKVAdapterOptions);
+    private key;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+
+export { VercelKVIdempotencyCache, VercelKVOAuthTokenStore, VercelKVSubscriptionStateAdapter };

package/dist/vercel-kv.js

@@ -0,0 +1,88 @@
+import { kv } from '@vercel/kv';
+
+// src/vercel-kv.ts
+var DEFAULT_SUBSCRIPTION_PREFIX = "mp:sub:";
+var DEFAULT_OAUTH_PREFIX = "mp:oauth:";
+var DEFAULT_IDEMPOTENCY_PREFIX = "mp:idem:";
+var VercelKVSubscriptionStateAdapter = class {
+  kv;
+  prefix;
+  indexKey;
+  constructor(options = {}) {
+    this.kv = options.kv ?? kv;
+    this.prefix = options.prefix ?? DEFAULT_SUBSCRIPTION_PREFIX;
+    this.indexKey = `${this.prefix}__index`;
+  }
+  key(id) {
+    return `${this.prefix}${id}`;
+  }
+  async set(id, state) {
+    const existing = await this.kv.get(this.key(id)) ?? {};
+    await this.kv.set(this.key(id), { ...existing, ...state });
+    await this.kv.sadd(this.indexKey, id);
+  }
+  async get(id) {
+    return await this.kv.get(this.key(id)) ?? null;
+  }
+  async list() {
+    const ids = await this.kv.smembers(this.indexKey);
+    return ids.map(String);
+  }
+  /** Forget a subscription record. NOT part of the adapter interface. */
+  async delete(id) {
+    await this.kv.del(this.key(id));
+    await this.kv.srem(this.indexKey, id);
+  }
+};
+var VercelKVOAuthTokenStore = class {
+  kv;
+  prefix;
+  indexKey;
+  constructor(options = {}) {
+    this.kv = options.kv ?? kv;
+    this.prefix = options.prefix ?? DEFAULT_OAUTH_PREFIX;
+    this.indexKey = `${this.prefix}__index`;
+  }
+  key(userId) {
+    return `${this.prefix}${userId}`;
+  }
+  async set(userId, token) {
+    await this.kv.set(this.key(userId), token);
+    await this.kv.sadd(this.indexKey, userId);
+  }
+  async get(userId) {
+    return await this.kv.get(this.key(userId)) ?? null;
+  }
+  async delete(userId) {
+    await this.kv.del(this.key(userId));
+    await this.kv.srem(this.indexKey, userId);
+  }
+  async list() {
+    const ids = await this.kv.smembers(this.indexKey);
+    return ids.map(String);
+  }
+};
+var VercelKVIdempotencyCache = class {
+  kv;
+  prefix;
+  constructor(options = {}) {
+    this.kv = options.kv ?? kv;
+    this.prefix = options.prefix ?? DEFAULT_IDEMPOTENCY_PREFIX;
+  }
+  key(k) {
+    return `${this.prefix}${k}`;
+  }
+  async get(key) {
+    return await this.kv.get(this.key(key)) ?? null;
+  }
+  async set(key, value, ttlSeconds = 86400) {
+    await this.kv.set(this.key(key), value, { ex: ttlSeconds });
+  }
+  async delete(key) {
+    await this.kv.del(this.key(key));
+  }
+};
+
+export { VercelKVIdempotencyCache, VercelKVOAuthTokenStore, VercelKVSubscriptionStateAdapter };
+//# sourceMappingURL=vercel-kv.js.map
+//# sourceMappingURL=vercel-kv.js.map

package/dist/vercel-kv.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vercel-kv.ts"],"names":["defaultKv"],"mappings":"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","file":"vercel-kv.js","sourcesContent":["/**\n * Vercel KV adapters — drop-in `SubscriptionStateAdapter`,\n * `OAuthTokenStore`, and `IdempotencyCache` implementations backed by\n * [Vercel KV](https://vercel.com/docs/storage/vercel-kv) (Upstash Redis).\n *\n * # Why a separate subpath?\n *\n * `@vercel/kv` is a peer dependency — only consumers who actually use Vercel\n * KV install it. Importing from `@ar-agents/mercadopago/vercel-kv` is\n * lazy: the main `@ar-agents/mercadopago` bundle stays tiny for callers who\n * use the in-memory adapters or a different store.\n *\n * # Setup\n *\n * 1. Create a KV store at https://vercel.com/dashboard/stores\n * 2. Connect it to your project — Vercel auto-injects `KV_*` env vars\n * 3. `pnpm add @vercel/kv`\n * 4. Wire the adapters:\n *\n *    ```ts\n *    import { mercadoPagoTools, MercadoPagoClient } from \"@ar-agents/mercadopago\";\n *    import {\n *      VercelKVSubscriptionStateAdapter,\n *      VercelKVOAuthTokenStore,\n *    } from \"@ar-agents/mercadopago/vercel-kv\";\n *\n *    const tools = mercadoPagoTools(client, {\n *      state: new VercelKVSubscriptionStateAdapter(),\n *      backUrl: \"https://mysite.com/done\",\n *      // ... oauth, webhookSecret, etc.\n *    });\n *\n *    // For marketplace flows, also wire the OAuth token store:\n *    const oauthStore = new VercelKVOAuthTokenStore();\n *    await oauthStore.set(token.user_id, {\n *      user_id: token.user_id,\n *      access_token: token.access_token,\n *      refresh_token: token.refresh_token!,\n *      expires_at: Date.now() + (token.expires_in ?? 21600) * 1000,\n *    });\n *    ```\n *\n * # Edge Runtime\n *\n * `@vercel/kv` works in Vercel Edge Runtime, Node.js, and any environment\n * with `fetch` (it's a thin REST client over Upstash). All adapters here\n * are async and Edge-safe.\n *\n * # Key namespacing\n *\n * Each adapter uses its own prefix so multiple adapters can share the same\n * KV store without collisions:\n * - Subscriptions: `mp:sub:{id}`\n * - OAuth tokens:  `mp:oauth:{userId}`\n * - Idempotency:   `mp:idem:{key}`\n *\n * Pass a custom prefix via the constructor if you need to share the store\n * with other apps.\n */\n\nimport { kv as defaultKv } from \"@vercel/kv\";\nimport type { VercelKV } from \"@vercel/kv\";\nimport type {\n  IdempotencyCache,\n  OAuthTokenRecord,\n  OAuthTokenStore,\n  SubscriptionStateAdapter,\n  SubscriptionStateRecord,\n} from \"./state\";\n\nconst DEFAULT_SUBSCRIPTION_PREFIX = \"mp:sub:\";\nconst DEFAULT_OAUTH_PREFIX = \"mp:oauth:\";\nconst DEFAULT_IDEMPOTENCY_PREFIX = \"mp:idem:\";\n\ninterface VercelKVAdapterOptions {\n  /**\n   * Custom KV client. If omitted, uses the default `kv` export from\n   * `@vercel/kv` (which reads `KV_REST_API_URL` + `KV_REST_API_TOKEN` from\n   * env — auto-injected when you connect a KV store to your Vercel project).\n   */\n  kv?: VercelKV;\n  /** Override the key prefix. */\n  prefix?: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// SubscriptionStateAdapter\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport class VercelKVSubscriptionStateAdapter\n  implements SubscriptionStateAdapter\n{\n  private readonly kv: VercelKV;\n  private readonly prefix: string;\n  private readonly indexKey: string;\n\n  constructor(options: VercelKVAdapterOptions = {}) {\n    this.kv = options.kv ?? defaultKv;\n    this.prefix = options.prefix ?? DEFAULT_SUBSCRIPTION_PREFIX;\n    this.indexKey = `${this.prefix}__index`;\n  }\n\n  private key(id: string): string {\n    return `${this.prefix}${id}`;\n  }\n\n  async set(\n    id: string,\n    state: Partial<SubscriptionStateRecord>,\n  ): Promise<void> {\n    const existing = (await this.kv.get<SubscriptionStateRecord>(this.key(id))) ?? {};\n    await this.kv.set(this.key(id), { ...existing, ...state });\n    await this.kv.sadd(this.indexKey, id);\n  }\n\n  async get(id: string): Promise<SubscriptionStateRecord | null> {\n    return (await this.kv.get<SubscriptionStateRecord>(this.key(id))) ?? null;\n  }\n\n  async list(): Promise<string[]> {\n    const ids = await this.kv.smembers(this.indexKey);\n    return ids.map(String);\n  }\n\n  /** Forget a subscription record. NOT part of the adapter interface. */\n  async delete(id: string): Promise<void> {\n    await this.kv.del(this.key(id));\n    await this.kv.srem(this.indexKey, id);\n  }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// OAuthTokenStore (per-seller marketplace token persistence)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport class VercelKVOAuthTokenStore implements OAuthTokenStore {\n  private readonly kv: VercelKV;\n  private readonly prefix: string;\n  private readonly indexKey: string;\n\n  constructor(options: VercelKVAdapterOptions = {}) {\n    this.kv = options.kv ?? defaultKv;\n    this.prefix = options.prefix ?? DEFAULT_OAUTH_PREFIX;\n    this.indexKey = `${this.prefix}__index`;\n  }\n\n  private key(userId: string): string {\n    return `${this.prefix}${userId}`;\n  }\n\n  async set(userId: string, token: OAuthTokenRecord): Promise<void> {\n    await this.kv.set(this.key(userId), token);\n    await this.kv.sadd(this.indexKey, userId);\n  }\n\n  async get(userId: string): Promise<OAuthTokenRecord | null> {\n    return (await this.kv.get<OAuthTokenRecord>(this.key(userId))) ?? null;\n  }\n\n  async delete(userId: string): Promise<void> {\n    await this.kv.del(this.key(userId));\n    await this.kv.srem(this.indexKey, userId);\n  }\n\n  async list(): Promise<string[]> {\n    const ids = await this.kv.smembers(this.indexKey);\n    return ids.map(String);\n  }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// IdempotencyCache (KV-backed dedup of agent retries)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport class VercelKVIdempotencyCache implements IdempotencyCache {\n  private readonly kv: VercelKV;\n  private readonly prefix: string;\n\n  constructor(options: VercelKVAdapterOptions = {}) {\n    this.kv = options.kv ?? defaultKv;\n    this.prefix = options.prefix ?? DEFAULT_IDEMPOTENCY_PREFIX;\n  }\n\n  private key(k: string): string {\n    return `${this.prefix}${k}`;\n  }\n\n  async get<T>(key: string): Promise<T | null> {\n    return (await this.kv.get<T>(this.key(key))) ?? null;\n  }\n\n  async set<T>(key: string, value: T, ttlSeconds = 86_400): Promise<void> {\n    // Vercel KV's `set` supports a TTL in seconds via the `ex` option.\n    await this.kv.set(this.key(key), value, { ex: ttlSeconds });\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.kv.del(this.key(key));\n  }\n}\n"]}