@pulgueta/epayco-convex 0.1.0

package/src/component/tokens.ts

@@ -0,0 +1,89 @@
+import { v } from "convex/values";
+import { internalMutation, query } from "./_generated/server.js";
+
+/**
+ * Local persistence for tokenized cards. Card data itself is never stored —
+ * only the ePayco token id, masked PAN, and franchise.
+ */
+
+export const getLocalTokens = query({
+  args: { userId: v.string() },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const tokens = await ctx.db
+      .query("tokens")
+      .withIndex("by_userId", (q) => q.eq("userId", args.userId))
+      .take(100);
+    return tokens.filter((t) => t.isActive);
+  },
+});
+
+export const upsertToken = internalMutation({
+  args: {
+    userId: v.string(),
+    epaycoTokenId: v.string(),
+    epaycoCustomerId: v.string(),
+    mask: v.string(),
+    franchise: v.string(),
+    isActive: v.boolean(),
+    lastSyncedAt: v.number(),
+  },
+  returns: v.id("tokens"),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("tokens")
+      .withIndex("by_epaycoTokenId", (q) =>
+        q.eq("epaycoTokenId", args.epaycoTokenId),
+      )
+      .first();
+
+    if (existing) {
+      if (existing.lastSyncedAt >= args.lastSyncedAt) return existing._id;
+
+      const patch: Record<string, unknown> = {
+        mask: args.mask,
+        franchise: args.franchise,
+        isActive: args.isActive,
+        lastSyncedAt: args.lastSyncedAt,
+      };
+      // Only link/relink the customer when a non-empty id is provided, so a
+      // later card-only sync can't wipe an existing customer association.
+      if (args.epaycoCustomerId !== "") {
+        patch.epaycoCustomerId = args.epaycoCustomerId;
+      }
+      await ctx.db.patch(existing._id, patch);
+      return existing._id;
+    }
+
+    return await ctx.db.insert("tokens", {
+      userId: args.userId,
+      epaycoTokenId: args.epaycoTokenId,
+      epaycoCustomerId: args.epaycoCustomerId,
+      mask: args.mask,
+      franchise: args.franchise,
+      isActive: args.isActive,
+      lastSyncedAt: args.lastSyncedAt,
+    });
+  },
+});
+
+export const revokeToken = internalMutation({
+  args: { epaycoTokenId: v.string(), lastSyncedAt: v.number() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("tokens")
+      .withIndex("by_epaycoTokenId", (q) =>
+        q.eq("epaycoTokenId", args.epaycoTokenId),
+      )
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        isActive: false,
+        lastSyncedAt: args.lastSyncedAt,
+      });
+    }
+    return null;
+  },
+});

package/src/component/tokensApi.ts

@@ -0,0 +1,63 @@
+import { v } from "convex/values";
+import { action } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import { epaycoCredentialsValidator, tokenInfoValidator } from "./validators.js";
+import { getEpaycoClient, unwrap, dataOf, pick } from "./epaycoClient.js";
+import { rateLimiter } from "./rateLimits.js";
+
+/** Tokenize a card via ePayco and cache the resulting token locally. */
+export const createToken = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    userId: v.string(),
+    tokenInfo: tokenInfoValidator,
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    await rateLimiter.limit(ctx, "createToken", {
+      key: args.userId,
+      throws: true,
+    });
+
+    const epayco = getEpaycoClient(args.credentials);
+    const result = unwrap(
+      await epayco.token.create({
+        "card[number]": args.tokenInfo.cardNumber,
+        "card[exp_year]": args.tokenInfo.expYear,
+        "card[exp_month]": args.tokenInfo.expMonth,
+        "card[cvc]": args.tokenInfo.cvc,
+        hasCvv: args.tokenInfo.hasCvv ?? true,
+      }),
+    );
+
+    const data = dataOf(result);
+    // ePayco returns the card details (mask, franchise name) under `result.card`.
+    const card =
+      typeof result.card === "object" && result.card !== null
+        ? (result.card as Record<string, unknown>)
+        : {};
+    const tokenId =
+      pick(data, ["id", "token", "tokenId"]) ??
+      pick(result, ["id", "token", "tokenId"]);
+
+    if (tokenId) {
+      await ctx.runMutation(internal.tokens.upsertToken, {
+        userId: args.userId,
+        epaycoTokenId: tokenId,
+        epaycoCustomerId: "",
+        mask:
+          pick(data, ["mask"]) ??
+          pick(card, ["mask"]) ??
+          `****${args.tokenInfo.cardNumber.slice(-4)}`,
+        franchise:
+          pick(data, ["franchise"]) ??
+          pick(card, ["name", "franchise"]) ??
+          "unknown",
+        isActive: true,
+        lastSyncedAt: Date.now(),
+      });
+    }
+
+    return result;
+  },
+});

package/src/component/transactions.test.ts

@@ -0,0 +1,227 @@
+/// <reference types="vite/client" />
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { initConvexTest } from "./setup.test.helper.js";
+import { api, internal } from "./_generated/api.js";
+
+describe("transactions", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test("upsertTransaction creates a new transaction", async () => {
+    const t = initConvexTest();
+    const id = await t.mutation(internal.transactions.upsertTransaction, {
+      userId: "user1",
+      epaycoRef: "ref_001",
+      paymentMethod: "credit_card",
+      status: "approved",
+      amount: 50000,
+      currency: "COP",
+      description: "Test payment",
+      lastSyncedAt: 1000,
+    });
+    expect(id).toBeDefined();
+
+    const tx = await t.query(api.transactions.getLocalTransaction, {
+      epaycoRef: "ref_001",
+    });
+    expect(tx).not.toBeNull();
+    expect(tx!.amount).toBe(50000);
+    expect(tx!.status).toBe("approved");
+    expect(tx!.paymentMethod).toBe("credit_card");
+  });
+
+  test("upsertTransaction is idempotent", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.transactions.upsertTransaction, {
+      userId: "user1",
+      epaycoRef: "ref_002",
+      paymentMethod: "pse",
+      status: "pending",
+      amount: 100000,
+      currency: "COP",
+      description: "PSE payment",
+      lastSyncedAt: 1000,
+    });
+
+    // Same timestamp - should not update
+    await t.mutation(internal.transactions.upsertTransaction, {
+      userId: "user1",
+      epaycoRef: "ref_002",
+      paymentMethod: "pse",
+      status: "approved",
+      amount: 100000,
+      currency: "COP",
+      description: "PSE payment",
+      lastSyncedAt: 1000,
+    });
+
+    const tx = await t.query(api.transactions.getLocalTransaction, {
+      epaycoRef: "ref_002",
+    });
+    expect(tx!.status).toBe("pending");
+  });
+
+  test("upsertTransaction updates with newer timestamp", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.transactions.upsertTransaction, {
+      userId: "user1",
+      epaycoRef: "ref_003",
+      paymentMethod: "cash",
+      status: "pending",
+      amount: 75000,
+      currency: "COP",
+      description: "Cash payment",
+      lastSyncedAt: 1000,
+    });
+
+    await t.mutation(internal.transactions.upsertTransaction, {
+      userId: "user1",
+      epaycoRef: "ref_003",
+      paymentMethod: "cash",
+      status: "approved",
+      amount: 75000,
+      currency: "COP",
+      description: "Cash payment",
+      lastSyncedAt: 2000,
+    });
+
+    const tx = await t.query(api.transactions.getLocalTransaction, {
+      epaycoRef: "ref_003",
+    });
+    expect(tx!.status).toBe("approved");
+  });
+
+  test("listLocalTransactions filters by userId", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.transactions.upsertTransaction, {
+      userId: "user1",
+      epaycoRef: "ref_100",
+      paymentMethod: "credit_card",
+      status: "approved",
+      amount: 10000,
+      currency: "COP",
+      description: "TX 1",
+      lastSyncedAt: 1000,
+    });
+    await t.mutation(internal.transactions.upsertTransaction, {
+      userId: "user2",
+      epaycoRef: "ref_101",
+      paymentMethod: "pse",
+      status: "approved",
+      amount: 20000,
+      currency: "COP",
+      description: "TX 2",
+      lastSyncedAt: 1000,
+    });
+
+    const user1Txs = await t.query(api.transactions.listLocalTransactions, {
+      userId: "user1",
+    });
+    expect(user1Txs).toHaveLength(1);
+    expect(user1Txs[0].epaycoRef).toBe("ref_100");
+  });
+
+  test("listLocalTransactions filters by status", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.transactions.upsertTransaction, {
+      userId: "user1",
+      epaycoRef: "ref_200",
+      paymentMethod: "credit_card",
+      status: "approved",
+      amount: 10000,
+      currency: "COP",
+      description: "Approved TX",
+      lastSyncedAt: 1000,
+    });
+    await t.mutation(internal.transactions.upsertTransaction, {
+      userId: "user1",
+      epaycoRef: "ref_201",
+      paymentMethod: "credit_card",
+      status: "pending",
+      amount: 20000,
+      currency: "COP",
+      description: "Pending TX",
+      lastSyncedAt: 1000,
+    });
+
+    const approvedTxs = await t.query(api.transactions.listLocalTransactions, {
+      userId: "user1",
+      status: "approved",
+    });
+    expect(approvedTxs).toHaveLength(1);
+    expect(approvedTxs[0].status).toBe("approved");
+  });
+
+  test("updateTransactionStatus updates existing transaction", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.transactions.upsertTransaction, {
+      userId: "user1",
+      epaycoRef: "ref_300",
+      paymentMethod: "pse",
+      status: "pending",
+      amount: 50000,
+      currency: "COP",
+      description: "PSE TX",
+      lastSyncedAt: 1000,
+    });
+
+    await t.mutation(internal.transactions.updateTransactionStatus, {
+      epaycoRef: "ref_300",
+      status: "approved",
+      responseCode: "1",
+      responseMessage: "Aprobada",
+    });
+
+    const tx = await t.query(api.transactions.getLocalTransaction, {
+      epaycoRef: "ref_300",
+    });
+    expect(tx!.status).toBe("approved");
+    expect(tx!.responseCode).toBe("1");
+  });
+
+  test("upsertTransaction drains a confirmation that arrived first", async () => {
+    const t = initConvexTest();
+    // A verified confirmation lands before the local transaction exists, so the
+    // webhook handler parked it as a pending event.
+    await t.mutation(internal.webhooks.storeWebhookEvent, {
+      epaycoRef: "ref_race",
+      eventType: "confirmation",
+      status: "pending",
+      rawPayload: {
+        x_ref_payco: "ref_race",
+        x_cod_response: "1",
+        x_response_reason_text: "Aprobada",
+      },
+      lastSyncedAt: 1000,
+    });
+
+    // The charge action now persists the transaction (initially pending).
+    await t.mutation(internal.transactions.upsertTransaction, {
+      userId: "user1",
+      epaycoRef: "ref_race",
+      paymentMethod: "pse",
+      status: "pending",
+      amount: 50000,
+      currency: "COP",
+      description: "PSE TX",
+      lastSyncedAt: 2000,
+    });
+
+    // The waiting confirmation is applied on insert, not dropped.
+    const tx = await t.query(api.transactions.getLocalTransaction, {
+      epaycoRef: "ref_race",
+    });
+    expect(tx!.status).toBe("approved");
+    expect(tx!.responseCode).toBe("1");
+    expect(tx!.responseMessage).toBe("Aprobada");
+
+    const event = await t.query(internal.webhooks.getWebhookEvent, {
+      epaycoRef: "ref_race",
+    });
+    expect(event!.status).toBe("processed");
+  });
+});

package/src/component/transactions.ts

@@ -0,0 +1,200 @@
+import { v } from "convex/values";
+import { internalMutation, query } from "./_generated/server.js";
+import { paymentMethodValidator } from "./validators.js";
+import { statusFromCodResponse } from "./status.js";
+
+export const getLocalTransaction = query({
+  args: { epaycoRef: v.string() },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("transactions")
+      .withIndex("by_epaycoRef", (q) => q.eq("epaycoRef", args.epaycoRef))
+      .first();
+  },
+});
+
+export const listLocalTransactions = query({
+  args: {
+    userId: v.string(),
+    status: v.optional(v.string()),
+    paymentMethod: v.optional(paymentMethodValidator),
+    limit: v.optional(v.number()),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    let q;
+    if (args.status) {
+      q = ctx.db
+        .query("transactions")
+        .withIndex("by_userId_and_status", (q) =>
+          q.eq("userId", args.userId).eq("status", args.status!),
+        );
+    } else {
+      q = ctx.db
+        .query("transactions")
+        .withIndex("by_userId", (q) => q.eq("userId", args.userId));
+    }
+
+    if (args.paymentMethod) {
+      q = q.filter((q) =>
+        q.eq(q.field("paymentMethod"), args.paymentMethod),
+      );
+    }
+
+    return await q.order("desc").take(args.limit ?? 100);
+  },
+});
+
+export const upsertTransaction = internalMutation({
+  args: {
+    userId: v.string(),
+    epaycoRef: v.string(),
+    epaycoTransactionId: v.optional(v.string()),
+    paymentMethod: paymentMethodValidator,
+    status: v.string(),
+    amount: v.number(),
+    currency: v.string(),
+    description: v.string(),
+    customerEmail: v.optional(v.string()),
+    bankName: v.optional(v.string()),
+    cashProvider: v.optional(v.string()),
+    responseCode: v.optional(v.string()),
+    responseMessage: v.optional(v.string()),
+    franchise: v.optional(v.string()),
+    splitPayment: v.optional(v.boolean()),
+    splitReceivers: v.optional(
+      v.array(
+        v.object({
+          id: v.string(),
+          total: v.number(),
+          iva: v.number(),
+          base_iva: v.number(),
+          fee: v.optional(v.number()),
+        }),
+      ),
+    ),
+    rawResponse: v.optional(v.any()),
+    lastSyncedAt: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("transactions")
+      .withIndex("by_epaycoRef", (q) => q.eq("epaycoRef", args.epaycoRef))
+      .first();
+
+    if (existing) {
+      if (existing.lastSyncedAt >= args.lastSyncedAt) return existing._id;
+
+      await ctx.db.patch(existing._id, {
+        status: args.status,
+        responseCode: args.responseCode,
+        responseMessage: args.responseMessage,
+        rawResponse: args.rawResponse,
+        lastSyncedAt: args.lastSyncedAt,
+      });
+      return existing._id;
+    }
+
+    const insertedId = await ctx.db.insert("transactions", {
+      userId: args.userId,
+      epaycoRef: args.epaycoRef,
+      epaycoTransactionId: args.epaycoTransactionId,
+      paymentMethod: args.paymentMethod,
+      status: args.status,
+      amount: args.amount,
+      currency: args.currency,
+      description: args.description,
+      customerEmail: args.customerEmail,
+      bankName: args.bankName,
+      cashProvider: args.cashProvider,
+      responseCode: args.responseCode,
+      responseMessage: args.responseMessage,
+      franchise: args.franchise,
+      splitPayment: args.splitPayment,
+      splitReceivers: args.splitReceivers,
+      rawResponse: args.rawResponse,
+      lastSyncedAt: args.lastSyncedAt,
+    });
+
+    // Reconcile a confirmation that arrived BEFORE this row existed: an async
+    // PSE/cash/Daviplata webhook can race ahead of (or be independent of) local
+    // persistence, in which case `webhooks.processConfirmation` verified it and
+    // parked the event as `pending`. Apply it now so the status is never lost.
+    await drainPendingConfirmation(ctx, args.epaycoRef, insertedId);
+
+    return insertedId;
+  },
+});
+
+/**
+ * If a verified-but-unapplied confirmation event is waiting for `epaycoRef`,
+ * apply its outcome to the (now-existing) transaction row and mark the event
+ * processed. Deterministic, so no cron/scheduler is needed; it runs whenever a
+ * transaction is first inserted. Safe no-op when nothing is waiting.
+ */
+async function drainPendingConfirmation(
+  ctx: { db: import("./_generated/server.js").MutationCtx["db"] },
+  epaycoRef: string,
+  transactionId: import("./_generated/dataModel.js").Id<"transactions">,
+): Promise<void> {
+  const event = await ctx.db
+    .query("webhookEvents")
+    .withIndex("by_epaycoRef", (q) => q.eq("epaycoRef", epaycoRef))
+    .order("desc")
+    .first();
+  if (!event || event.status !== "pending") return;
+
+  const payload = (event.rawPayload ?? {}) as Record<string, unknown>;
+  const cod = payload.x_cod_response;
+  if (cod === undefined || cod === null) return;
+
+  const reason = payload.x_response_reason_text ?? payload.x_response;
+  await ctx.db.patch(transactionId, {
+    status: statusFromCodResponse(String(cod)),
+    responseCode: String(cod),
+    responseMessage:
+      reason === undefined || reason === null ? undefined : String(reason),
+    rawResponse: payload,
+    lastSyncedAt: Date.now(),
+  });
+  await ctx.db.patch(event._id, {
+    status: "processed",
+    processedAt: Date.now(),
+    lastSyncedAt: Date.now(),
+  });
+}
+
+/**
+ * Patch the status of an existing transaction. Returns `true` when a row was
+ * found and updated, `false` when no local row exists yet — so callers (e.g. the
+ * webhook handler) can detect a confirmation that arrived before local
+ * persistence instead of silently dropping it.
+ */
+export const updateTransactionStatus = internalMutation({
+  args: {
+    epaycoRef: v.string(),
+    status: v.string(),
+    responseCode: v.optional(v.string()),
+    responseMessage: v.optional(v.string()),
+    rawResponse: v.optional(v.any()),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("transactions")
+      .withIndex("by_epaycoRef", (q) => q.eq("epaycoRef", args.epaycoRef))
+      .first();
+
+    if (!existing) return false;
+
+    await ctx.db.patch(existing._id, {
+      status: args.status,
+      responseCode: args.responseCode,
+      responseMessage: args.responseMessage,
+      rawResponse: args.rawResponse,
+      lastSyncedAt: Date.now(),
+    });
+    return true;
+  },
+});