@ar-agents/mercadopago 0.10.0 → 0.11.0

package/dist/audit-B9Nhj3PH.d.ts

@@ -0,0 +1,294 @@
+/**
+ * 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;
+}
+
+/**
+ * Compute SHA-256 hash of `input`. Returns the full 64-char hex digest.
+ *
+ * Used for deterministic idempotency keys derived from caller-meaningful
+ * fields. Truncate the output to 32 chars for storage if needed.
+ */
+declare function sha256Hex(input: string): Promise<string>;
+
+/**
+ * Audit logging — financial-grade compliance trail for every state-mutating
+ * operation. Captures who/what/when/idempotency_key/before/after/result.
+ *
+ * # Why this is a tier-1 feature
+ *
+ * Every mature payment integration has an audit log. The compliance officer
+ * asks "show me every refund issued in March 2026 by user X" and you need
+ * to answer in <60 seconds. Without an audit log, you're trawling through
+ * application logs hoping nothing was filtered out.
+ *
+ * # What gets logged
+ *
+ * Every **state-mutating** tool call automatically:
+ * - `create_payment`, `charge_saved_card`, `cancel_payment`, `capture_payment`
+ * - `refund_payment`
+ * - `create_subscription`, `cancel/pause/resume_subscription`, `update_subscription`
+ * - `create_order`, `capture_order`, `cancel_order`
+ * - `create_payment_preference`, `update_payment_preference`
+ * - `create_customer`, `update_customer`, `create_customer_card`, `delete_customer_card`
+ * - `create_subscription_plan`, `update_subscription_plan`
+ * - `create_store/pos`, `update_store/pos`, `delete_store/pos`
+ * - `create_qr_payment`, `cancel_qr_payment`
+ * - `create_point_payment_intent`, `cancel_point_payment_intent`, `update_point_device_mode`
+ * - OAuth: `oauth_exchange_code`, `oauth_refresh_token`
+ * - `register_bank_account`
+ * - `create_webhook`, `update_webhook`, `delete_webhook`
+ *
+ * **Read-only** tools do NOT emit audit entries (would flood the log without
+ * value): get_*, search_*, list_*, calculate_*, validate_*, lookup_*, analyze_*.
+ *
+ * # PII handling
+ *
+ * The audit log captures `inputSummary` (a deterministic hash of the input
+ * fields, NOT the raw input) by default. Configure `redact: false` to log
+ * raw inputs (payer email, CUIT, etc.) — only when your data-residency
+ * policy permits.
+ *
+ * # Storage
+ *
+ * Pluggable adapter pattern. Ships:
+ * - `InMemoryAuditLog` — for tests + single-process demos.
+ * - `VercelKVAuditLog` (in `/vercel-kv` subpath) — production-ready, KV-backed
+ *   with daily-bucket indexing for efficient time-range queries.
+ *
+ * Implement your own for Postgres / S3 / SIEM integration.
+ */
+
+type AuditOperation = "create_payment" | "charge_saved_card" | "cancel_payment" | "capture_payment" | "refund_payment" | "create_subscription" | "cancel_subscription" | "pause_subscription" | "resume_subscription" | "update_subscription" | "subscribe_to_plan" | "create_subscription_plan" | "update_subscription_plan" | "create_order" | "capture_order" | "cancel_order" | "update_order" | "create_payment_preference" | "update_payment_preference" | "create_customer" | "update_customer" | "create_customer_card" | "delete_customer_card" | "create_store" | "update_store" | "delete_store" | "create_pos" | "update_pos" | "delete_pos" | "create_qr_payment" | "cancel_qr_payment" | "create_point_payment_intent" | "cancel_point_payment_intent" | "update_point_device_mode" | "oauth_exchange_code" | "oauth_refresh_token" | "register_bank_account" | "create_webhook" | "update_webhook" | "delete_webhook" | (string & {});
+interface AuditEntry {
+    /**
+     * Unique entry id. Format: `mpaud-{ISO date}-{random}`. Use as primary
+     * key in your storage layer.
+     */
+    id: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** The MP operation performed. */
+    operation: AuditOperation;
+    /**
+     * Logical actor that initiated the call. Caller-provided. Examples:
+     * `"agent:billing-bot"`, `"user:42"`, `"cron:daily-charge"`.
+     *
+     * Defaults to `"unknown"` when not provided. **Always pass this in
+     * production** — without it, your compliance trail is meaningless.
+     */
+    actor: string;
+    /** Optional tenant/seller id for multi-tenant marketplace setups. */
+    tenantId?: string;
+    /**
+     * SHA-256 hex of the meaningful input fields (deterministic). Useful as
+     * a join key with the IdempotencyCache. Does NOT contain raw PII.
+     */
+    inputHash: string;
+    /**
+     * Optional raw input — only populated when `redact: false` was configured.
+     * Defaults to undefined to comply with data-minimization principles.
+     */
+    inputRaw?: Record<string, unknown>;
+    /** Outcome: success or error code. */
+    outcome: "ok" | "error";
+    /** Error code when `outcome === "error"`. */
+    errorCode?: string;
+    /** Error message when `outcome === "error"`. */
+    errorMessage?: string;
+    /**
+     * MP resource id created/updated by the operation (e.g., payment id).
+     * Allows joining audit entries to the actual MP resource.
+     */
+    resourceId?: string;
+    /** Idempotency key passed to MP (for join with MP-side dedup logs). */
+    idempotencyKey?: string;
+    /** Duration in ms. */
+    durationMs?: number;
+    /** Free-form metadata bag. */
+    metadata?: Record<string, unknown>;
+}
+interface AuditLogAdapter {
+    append(entry: AuditEntry): Promise<void>;
+    /** Query a time range. Optional — implementations that don't support it can omit. */
+    query?(filter: {
+        actor?: string;
+        operation?: AuditOperation;
+        tenantId?: string;
+        from?: string;
+        to?: string;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+}
+/**
+ * Volatile, single-process audit log. Tests + dev only. Production deployments
+ * must use a durable adapter (`VercelKVAuditLog`, your Postgres/S3 impl, etc.)
+ */
+declare class InMemoryAuditLog implements AuditLogAdapter {
+    private readonly entries;
+    append(entry: AuditEntry): Promise<void>;
+    query(filter: {
+        actor?: string;
+        operation?: AuditOperation;
+        tenantId?: string;
+        from?: string;
+        to?: string;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+    /** All entries (test helper, not part of the adapter interface). */
+    all(): AuditEntry[];
+    reset(): void;
+}
+/**
+ * Audit logger — the user-facing facade that builds + ships entries.
+ *
+ * @example
+ * ```ts
+ * const audit = new AuditLogger({
+ *   adapter: new InMemoryAuditLog(),
+ *   defaultActor: "agent:billing-bot",
+ *   redact: true, // default — hashes input, no raw PII
+ * });
+ *
+ * const tools = mercadoPagoTools(client, {
+ *   state, backUrl, audit,
+ * });
+ * ```
+ */
+declare class AuditLogger {
+    private readonly adapter;
+    private readonly defaultActor;
+    private readonly redact;
+    private readonly hash;
+    constructor(options: {
+        adapter: AuditLogAdapter;
+        defaultActor?: string;
+        redact?: boolean;
+        /** Override hash (testing). */
+        hashFn?: typeof sha256Hex;
+    });
+    /**
+     * Wrap a tool execute() function with auto-audit. The returned function:
+     * 1. Computes inputHash before the call.
+     * 2. Invokes the original execute().
+     * 3. On success, appends an entry with outcome="ok" + resourceId.
+     * 4. On failure, appends an entry with outcome="error" + errorCode/Message.
+     * 5. Re-throws the error transparently.
+     */
+    record<I, O>(args: {
+        operation: AuditOperation;
+        input: I;
+        actor?: string;
+        tenantId?: string;
+        idempotencyKey?: string;
+        /**
+         * Function that extracts the resourceId from the result. Default: tries
+         * `result.id`, `result.payment_id`, `result.subscription_id`, `result.order_id`.
+         */
+        extractResourceId?: (result: O) => string | undefined;
+        /** The actual operation to execute. */
+        fn: () => Promise<O>;
+    }): Promise<O>;
+}
+
+export { AuditLogger as A, type IdempotencyCache as I, type OAuthTokenRecord as O, type SubscriptionStateAdapter as S, type AuditOperation as a, type AuditEntry as b, type AuditLogAdapter as c, InMemoryAuditLog as d, InMemoryIdempotencyCache as e, InMemoryOAuthTokenStore as f, InMemoryStateAdapter as g, type OAuthTokenStore as h, type SubscriptionStateRecord as i };