@pulgueta/epayco-convex 0.1.0

package/src/component/schema.ts

@@ -0,0 +1,124 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  customers: defineTable({
+    userId: v.string(),
+    epaycoCustomerId: v.string(),
+    name: v.string(),
+    email: v.string(),
+    phone: v.optional(v.string()),
+    docType: v.optional(v.string()),
+    docNumber: v.optional(v.string()),
+    defaultCard: v.optional(v.string()),
+    lastSyncedAt: v.number(),
+  })
+    .index("by_userId", ["userId"])
+    .index("by_epaycoCustomerId", ["epaycoCustomerId"])
+    .index("by_email", ["email"]),
+
+  tokens: defineTable({
+    userId: v.string(),
+    epaycoTokenId: v.string(),
+    epaycoCustomerId: v.string(),
+    mask: v.string(),
+    franchise: v.string(),
+    isActive: v.boolean(),
+    lastSyncedAt: v.number(),
+  })
+    .index("by_userId", ["userId"])
+    .index("by_epaycoTokenId", ["epaycoTokenId"]),
+
+  transactions: defineTable({
+    userId: v.string(),
+    epaycoRef: v.string(),
+    epaycoTransactionId: v.optional(v.string()),
+    paymentMethod: v.union(
+      v.literal("credit_card"),
+      v.literal("pse"),
+      v.literal("cash"),
+      v.literal("daviplata"),
+      v.literal("safetypay"),
+    ),
+    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(),
+  })
+    .index("by_userId", ["userId"])
+    .index("by_epaycoRef", ["epaycoRef"])
+    .index("by_userId_and_status", ["userId", "status"]),
+
+  plans: defineTable({
+    epaycoPlanId: v.string(),
+    name: v.string(),
+    description: v.string(),
+    amount: v.number(),
+    currency: v.string(),
+    interval: v.string(),
+    intervalCount: v.number(),
+    trialDays: v.number(),
+    status: v.string(),
+    lastSyncedAt: v.number(),
+  })
+    .index("by_epaycoPlanId", ["epaycoPlanId"])
+    .index("by_status", ["status"]),
+
+  subscriptions: defineTable({
+    userId: v.string(),
+    epaycoSubscriptionId: v.string(),
+    epaycoCustomerId: v.string(),
+    epaycoPlanId: v.string(),
+    epaycoTokenId: v.optional(v.string()),
+    status: v.string(),
+    currentPeriodStart: v.optional(v.number()),
+    currentPeriodEnd: v.optional(v.number()),
+    lastSyncedAt: v.number(),
+  })
+    .index("by_userId", ["userId"])
+    .index("by_epaycoSubscriptionId", ["epaycoSubscriptionId"])
+    .index("by_customerId_and_status", ["epaycoCustomerId", "status"]),
+
+  banks: defineTable({
+    bankCode: v.string(),
+    bankName: v.string(),
+    lastSyncedAt: v.number(),
+  }).index("by_bankCode", ["bankCode"]),
+
+  webhookEvents: defineTable({
+    epaycoRef: v.string(),
+    epaycoTransactionId: v.optional(v.string()),
+    eventType: v.string(),
+    status: v.union(
+      v.literal("pending"),
+      v.literal("processed"),
+      v.literal("failed"),
+    ),
+    rawPayload: v.any(),
+    errorMessage: v.optional(v.string()),
+    processedAt: v.optional(v.number()),
+    lastSyncedAt: v.number(),
+  })
+    .index("by_epaycoRef", ["epaycoRef"])
+    .index("by_status", ["status"]),
+});

package/src/component/setup.test.helper.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+import { convexTest } from "convex-test";
+import schema from "./schema.js";
+
+const modules = import.meta.glob("./**/*.ts");
+
+export function initConvexTest() {
+  const t = convexTest(schema, modules);
+  return t;
+}

package/src/component/setup.test.ts

@@ -0,0 +1,22 @@
+/// <reference types="vite/client" />
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { api } from "./_generated/api.js";
+import { initConvexTest } from "./setup.test.helper.js";
+
+export { initConvexTest };
+
+describe("component setup", () => {
+  beforeEach(async () => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+  test("schema tables exist", async () => {
+    const t = initConvexTest();
+    // Verify we can query the customers table
+    const customers = await t.query(api.customers.listLocalCustomers, {});
+    expect(customers).toEqual([]);
+  });
+});

package/src/component/signature.ts

@@ -0,0 +1,38 @@
+/**
+ * ePayco webhook (confirmation) signature verification.
+ *
+ * ePayco signs each confirmation with:
+ *   SHA256( p_cust_id_cliente ^ p_key ^ x_ref_payco ^ x_transaction_id ^ x_amount ^ x_currency_code )
+ *
+ * This runs in the default Convex (V8) runtime using Web Crypto — no Node
+ * built-ins required — so it is safe to import from queries/mutations/actions.
+ */
+export async function verifyWebhookSignature(
+  custIdCliente: string,
+  pKey: string,
+  xRefPayco: string,
+  xTransactionId: string,
+  xAmount: string,
+  xCurrencyCode: string,
+  receivedSignature: string,
+): Promise<boolean> {
+  const data = `${custIdCliente}^${pKey}^${xRefPayco}^${xTransactionId}^${xAmount}^${xCurrencyCode}`;
+  const hashBuffer = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(data),
+  );
+  const computedSignature = Array.from(new Uint8Array(hashBuffer))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  return timingSafeEqual(computedSignature, receivedSignature);
+}
+
+/** Constant-time string comparison to avoid leaking timing information. */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i++) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return mismatch === 0;
+}

package/src/component/status.ts

@@ -0,0 +1,71 @@
+/**
+ * Normalization of ePayco transaction states into the component's canonical
+ * status vocabulary: pending | approved | rejected | failed | expired | reversed.
+ *
+ * Pure functions, safe in any runtime.
+ */
+export type TransactionStatus =
+  | "pending"
+  | "approved"
+  | "rejected"
+  | "failed"
+  | "expired"
+  | "reversed";
+
+/** Map ePayco's `x_cod_response` (webhook) numeric code to a canonical status. */
+export function statusFromCodResponse(cod: string | number): TransactionStatus {
+  switch (String(cod)) {
+    case "1":
+      return "approved";
+    case "2":
+    case "11":
+    case "12":
+      return "rejected";
+    case "3":
+    case "7":
+      return "pending";
+    case "4":
+      return "failed";
+    case "6":
+      return "reversed";
+    case "9":
+      // 9 = Expirada (expired).
+      return "expired";
+    case "10":
+      // 10 = Abandonada — aligned with statusFromEstado("abandonada") => failed.
+      return "failed";
+    default:
+      return "pending";
+  }
+}
+
+/** Map ePayco's textual `estado` / `x_response` to a canonical status. */
+export function statusFromEstado(
+  estado: string | undefined | null,
+): TransactionStatus {
+  switch ((estado ?? "").toLowerCase().trim()) {
+    case "aceptada":
+    case "approved":
+      return "approved";
+    case "rechazada":
+    case "rejected":
+      return "rejected";
+    case "pendiente":
+    case "pending":
+      return "pending";
+    case "fallida":
+    case "abandonada":
+    case "failed":
+      return "failed";
+    case "cancelada":
+      return "rejected";
+    case "reversada":
+    case "reversed":
+      return "reversed";
+    case "expirada":
+    case "expired":
+      return "expired";
+    default:
+      return "pending";
+  }
+}

package/src/component/subscriptions.test.ts

@@ -0,0 +1,117 @@
+/// <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("subscriptions", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test("upsertSubscription creates a new subscription", async () => {
+    const t = initConvexTest();
+    const id = await t.mutation(internal.subscriptions.upsertSubscription, {
+      userId: "user1",
+      epaycoSubscriptionId: "sub_001",
+      epaycoCustomerId: "cust_001",
+      epaycoPlanId: "plan_basic",
+      status: "active",
+      lastSyncedAt: 1000,
+    });
+    expect(id).toBeDefined();
+
+    const sub = await t.query(api.subscriptions.getLocalSubscription, {
+      epaycoSubscriptionId: "sub_001",
+    });
+    expect(sub).not.toBeNull();
+    expect(sub!.status).toBe("active");
+    expect(sub!.userId).toBe("user1");
+  });
+
+  test("upsertSubscription is idempotent", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.subscriptions.upsertSubscription, {
+      userId: "user1",
+      epaycoSubscriptionId: "sub_002",
+      epaycoCustomerId: "cust_001",
+      epaycoPlanId: "plan_basic",
+      status: "active",
+      lastSyncedAt: 1000,
+    });
+
+    await t.mutation(internal.subscriptions.upsertSubscription, {
+      epaycoSubscriptionId: "sub_002",
+      status: "cancelled",
+      lastSyncedAt: 1000,
+    });
+
+    const sub = await t.query(api.subscriptions.getLocalSubscription, {
+      epaycoSubscriptionId: "sub_002",
+    });
+    expect(sub!.status).toBe("active");
+  });
+
+  test("getActiveSubscription returns active sub", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.subscriptions.upsertSubscription, {
+      userId: "user1",
+      epaycoSubscriptionId: "sub_010",
+      epaycoCustomerId: "cust_001",
+      epaycoPlanId: "plan_basic",
+      status: "active",
+      lastSyncedAt: 1000,
+    });
+
+    const active = await t.query(api.subscriptions.getActiveSubscription, {
+      userId: "user1",
+    });
+    expect(active).not.toBeNull();
+    expect(active!.epaycoSubscriptionId).toBe("sub_010");
+  });
+
+  test("getActiveSubscription returns null for cancelled", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.subscriptions.upsertSubscription, {
+      userId: "user1",
+      epaycoSubscriptionId: "sub_020",
+      epaycoCustomerId: "cust_001",
+      epaycoPlanId: "plan_basic",
+      status: "cancelled",
+      lastSyncedAt: 1000,
+    });
+
+    const active = await t.query(api.subscriptions.getActiveSubscription, {
+      userId: "user1",
+    });
+    expect(active).toBeNull();
+  });
+
+  test("listLocalSubscriptionsByUser excludes cancelled", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.subscriptions.upsertSubscription, {
+      userId: "user1",
+      epaycoSubscriptionId: "sub_030",
+      epaycoCustomerId: "cust_001",
+      epaycoPlanId: "plan_basic",
+      status: "active",
+      lastSyncedAt: 1000,
+    });
+    await t.mutation(internal.subscriptions.upsertSubscription, {
+      userId: "user1",
+      epaycoSubscriptionId: "sub_031",
+      epaycoCustomerId: "cust_001",
+      epaycoPlanId: "plan_pro",
+      status: "cancelled",
+      lastSyncedAt: 1000,
+    });
+
+    const subs = await t.query(api.subscriptions.listLocalSubscriptionsByUser, {
+      userId: "user1",
+    });
+    expect(subs).toHaveLength(1);
+    expect(subs[0].epaycoSubscriptionId).toBe("sub_030");
+  });
+});

package/src/component/subscriptions.ts

@@ -0,0 +1,128 @@
+import { v } from "convex/values";
+import { internalMutation, query } from "./_generated/server.js";
+
+/** Local persistence for subscriptions. */
+
+export const getLocalSubscription = query({
+  args: { epaycoSubscriptionId: v.string() },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("subscriptions")
+      .withIndex("by_epaycoSubscriptionId", (q) =>
+        q.eq("epaycoSubscriptionId", args.epaycoSubscriptionId),
+      )
+      .first();
+  },
+});
+
+export const listLocalSubscriptionsByUser = query({
+  args: { userId: v.string() },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const subs = await ctx.db
+      .query("subscriptions")
+      .withIndex("by_userId", (q) => q.eq("userId", args.userId))
+      .order("desc")
+      .take(100);
+    return subs.filter((s) => s.status !== "cancelled");
+  },
+});
+
+export const getActiveSubscription = query({
+  args: { userId: v.string() },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const subs = await ctx.db
+      .query("subscriptions")
+      .withIndex("by_userId", (q) => q.eq("userId", args.userId))
+      .order("desc")
+      .take(100);
+    return subs.find((s) => s.status === "active") ?? null;
+  },
+});
+
+/**
+ * Patch the status of an existing subscription only. Unlike `upsertSubscription`
+ * this never inserts, so cancelling a subscription that was never persisted
+ * locally (e.g. created out-of-band) can't create an orphan row with empty
+ * identity fields. Returns whether a row was found and updated.
+ */
+export const updateSubscriptionStatus = internalMutation({
+  args: {
+    epaycoSubscriptionId: v.string(),
+    status: v.string(),
+    lastSyncedAt: v.number(),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("subscriptions")
+      .withIndex("by_epaycoSubscriptionId", (q) =>
+        q.eq("epaycoSubscriptionId", args.epaycoSubscriptionId),
+      )
+      .first();
+
+    if (!existing) return false;
+    if (existing.lastSyncedAt >= args.lastSyncedAt) return true;
+
+    await ctx.db.patch(existing._id, {
+      status: args.status,
+      lastSyncedAt: args.lastSyncedAt,
+    });
+    return true;
+  },
+});
+
+export const upsertSubscription = internalMutation({
+  args: {
+    userId: v.optional(v.string()),
+    epaycoSubscriptionId: v.string(),
+    epaycoCustomerId: v.optional(v.string()),
+    epaycoPlanId: v.optional(v.string()),
+    epaycoTokenId: v.optional(v.string()),
+    status: v.string(),
+    currentPeriodStart: v.optional(v.number()),
+    currentPeriodEnd: v.optional(v.number()),
+    lastSyncedAt: v.number(),
+  },
+  returns: v.id("subscriptions"),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("subscriptions")
+      .withIndex("by_epaycoSubscriptionId", (q) =>
+        q.eq("epaycoSubscriptionId", args.epaycoSubscriptionId),
+      )
+      .first();
+
+    if (existing) {
+      if (existing.lastSyncedAt >= args.lastSyncedAt) return existing._id;
+
+      const patch: Record<string, unknown> = {
+        status: args.status,
+        lastSyncedAt: args.lastSyncedAt,
+      };
+      if (args.currentPeriodStart !== undefined)
+        patch.currentPeriodStart = args.currentPeriodStart;
+      if (args.currentPeriodEnd !== undefined)
+        patch.currentPeriodEnd = args.currentPeriodEnd;
+      if (args.epaycoTokenId !== undefined)
+        patch.epaycoTokenId = args.epaycoTokenId;
+
+      await ctx.db.patch(existing._id, patch);
+      return existing._id;
+    }
+
+    return await ctx.db.insert("subscriptions", {
+      userId: args.userId ?? "",
+      epaycoSubscriptionId: args.epaycoSubscriptionId,
+      epaycoCustomerId: args.epaycoCustomerId ?? "",
+      epaycoPlanId: args.epaycoPlanId ?? "",
+      epaycoTokenId: args.epaycoTokenId,
+      status: args.status,
+      currentPeriodStart: args.currentPeriodStart,
+      currentPeriodEnd: args.currentPeriodEnd,
+      lastSyncedAt: args.lastSyncedAt,
+    });
+  },
+});

package/src/component/subscriptionsApi.ts

@@ -0,0 +1,172 @@
+import { v } from "convex/values";
+import { action } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import {
+  epaycoCredentialsValidator,
+  subscriptionInfoValidator,
+} from "./validators.js";
+import { getEpaycoClient, unwrap, dataOf, pick } from "./epaycoClient.js";
+import { statusFromEstado } from "./status.js";
+import { rateLimiter } from "./rateLimits.js";
+
+/** Create a subscription (enroll a customer in a plan). */
+export const createSubscription = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    userId: v.string(),
+    subscriptionInfo: subscriptionInfoValidator,
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    await rateLimiter.limit(ctx, "createSubscription", {
+      key: args.userId,
+      throws: true,
+    });
+
+    const s = args.subscriptionInfo;
+    const epayco = getEpaycoClient(args.credentials);
+    const result = unwrap(
+      await epayco.subscriptions.create({
+        id_plan: s.idPlan,
+        customer: s.customer,
+        token_card: s.tokenCard,
+        doc_type: s.docType,
+        doc_number: s.docNumber,
+        ...(s.urlConfirmation ? { url_confirmation: s.urlConfirmation } : {}),
+        ...(s.methodConfirmation
+          ? { method_confirmation: s.methodConfirmation }
+          : {}),
+      }),
+    );
+
+    const data = dataOf(result);
+    const subscriptionId =
+      pick(data, ["id", "id_subscription", "subscription"]) ??
+      pick(result, ["id", "id_subscription"]);
+
+    if (subscriptionId) {
+      await ctx.runMutation(internal.subscriptions.upsertSubscription, {
+        userId: args.userId,
+        epaycoSubscriptionId: subscriptionId,
+        epaycoCustomerId: s.customer,
+        epaycoPlanId: s.idPlan,
+        epaycoTokenId: s.tokenCard,
+        status: pick(data, ["status"]) ?? "active",
+        lastSyncedAt: Date.now(),
+      });
+    }
+
+    return result;
+  },
+});
+
+export const getSubscription = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    epaycoSubscriptionId: v.string(),
+  },
+  returns: v.any(),
+  handler: async (_ctx, args) => {
+    const epayco = getEpaycoClient(args.credentials);
+    return unwrap(await epayco.subscriptions.get(args.epaycoSubscriptionId));
+  },
+});
+
+export const listSubscriptions = action({
+  args: { credentials: epaycoCredentialsValidator },
+  returns: v.any(),
+  handler: async (_ctx, args) => {
+    const epayco = getEpaycoClient(args.credentials);
+    return unwrap(await epayco.subscriptions.list());
+  },
+});
+
+export const cancelSubscription = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    epaycoSubscriptionId: v.string(),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const epayco = getEpaycoClient(args.credentials);
+    const result = unwrap(
+      await epayco.subscriptions.cancel(args.epaycoSubscriptionId),
+    );
+
+    // Update-only: never insert an orphan row for a subscription we don't track.
+    await ctx.runMutation(internal.subscriptions.updateSubscriptionStatus, {
+      epaycoSubscriptionId: args.epaycoSubscriptionId,
+      status: "cancelled",
+      lastSyncedAt: Date.now(),
+    });
+
+    return result;
+  },
+});
+
+/** Immediately charge a subscription's plan (one-off recurring payment). */
+export const chargeSubscription = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    userId: v.string(),
+    idPlan: v.string(),
+    customer: v.string(),
+    tokenCard: v.string(),
+    docType: v.string(),
+    docNumber: v.string(),
+    ip: v.optional(v.string()),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    await rateLimiter.limit(ctx, "chargeSubscription", {
+      key: args.userId,
+      throws: true,
+    });
+
+    const epayco = getEpaycoClient(args.credentials);
+    const result = unwrap(
+      await epayco.subscriptions.charge({
+        id_plan: args.idPlan,
+        customer: args.customer,
+        token_card: args.tokenCard,
+        doc_type: args.docType,
+        doc_number: args.docNumber,
+        ...(args.ip ? { ip: args.ip } : {}),
+      }),
+    );
+
+    // Record the resulting charge so recurring payments appear in local history.
+    // Subscription charges settle on a card, so they're stored as credit_card.
+    const data = dataOf(result);
+    const refPayco = pick(data, ["ref_payco", "refPayco"]);
+    if (refPayco) {
+      await ctx.runMutation(internal.transactions.upsertTransaction, {
+        userId: args.userId,
+        epaycoRef: refPayco,
+        epaycoTransactionId: pick(data, [
+          "transactionId",
+          "transaction_id",
+          "x_transaction_id",
+        ]),
+        paymentMethod: "credit_card",
+        status: statusFromEstado(
+          pick(data, ["estado", "x_response", "respuesta"]),
+        ),
+        amount: Number(pick(data, ["valor", "value", "x_amount", "amount"]) ?? 0),
+        currency: pick(data, ["moneda", "currency", "x_currency_code"]) ?? "COP",
+        description: `Subscription charge for plan ${args.idPlan}`,
+        franchise: pick(data, ["franchise", "franquicia", "x_franchise"]),
+        responseCode: pick(data, ["cod_respuesta", "x_cod_response"]),
+        responseMessage: pick(data, [
+          "respuesta",
+          "x_response_reason_text",
+          "response_reason_text",
+        ]),
+        rawResponse: data,
+        lastSyncedAt: Date.now(),
+      });
+    }
+
+    return result;
+  },
+});