@pulgueta/epayco-convex 0.1.0

package/src/component/plans.test.ts

@@ -0,0 +1,129 @@
+/// <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("plans", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test("upsertPlan creates a new plan", async () => {
+    const t = initConvexTest();
+    const id = await t.mutation(internal.plans.upsertPlan, {
+      epaycoPlanId: "plan_basic",
+      name: "Basic Plan",
+      description: "Basic monthly plan",
+      amount: 29900,
+      currency: "COP",
+      interval: "month",
+      intervalCount: 1,
+      trialDays: 7,
+      status: "active",
+      lastSyncedAt: 1000,
+    });
+    expect(id).toBeDefined();
+
+    const plan = await t.query(api.plans.getLocalPlan, {
+      epaycoPlanId: "plan_basic",
+    });
+    expect(plan).not.toBeNull();
+    expect(plan!.name).toBe("Basic Plan");
+    expect(plan!.amount).toBe(29900);
+  });
+
+  test("upsertPlan is idempotent with same timestamp", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.plans.upsertPlan, {
+      epaycoPlanId: "plan_pro",
+      name: "Pro Plan",
+      description: "Pro plan",
+      amount: 59900,
+      currency: "COP",
+      interval: "month",
+      intervalCount: 1,
+      trialDays: 0,
+      status: "active",
+      lastSyncedAt: 1000,
+    });
+
+    await t.mutation(internal.plans.upsertPlan, {
+      epaycoPlanId: "plan_pro",
+      name: "Pro Plan Updated",
+      lastSyncedAt: 1000,
+    });
+
+    const plan = await t.query(api.plans.getLocalPlan, {
+      epaycoPlanId: "plan_pro",
+    });
+    expect(plan!.name).toBe("Pro Plan");
+  });
+
+  test("listLocalPlans returns all plans", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.plans.upsertPlan, {
+      epaycoPlanId: "plan_1",
+      name: "Plan 1",
+      description: "First",
+      amount: 10000,
+      currency: "COP",
+      interval: "month",
+      intervalCount: 1,
+      trialDays: 0,
+      status: "active",
+      lastSyncedAt: 1000,
+    });
+    await t.mutation(internal.plans.upsertPlan, {
+      epaycoPlanId: "plan_2",
+      name: "Plan 2",
+      description: "Second",
+      amount: 20000,
+      currency: "COP",
+      interval: "year",
+      intervalCount: 1,
+      trialDays: 30,
+      status: "active",
+      lastSyncedAt: 1000,
+    });
+
+    const plans = await t.query(api.plans.listLocalPlans, {});
+    expect(plans).toHaveLength(2);
+  });
+
+  test("listLocalPlans filters by status", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.plans.upsertPlan, {
+      epaycoPlanId: "plan_active",
+      name: "Active",
+      description: "Active plan",
+      amount: 10000,
+      currency: "COP",
+      interval: "month",
+      intervalCount: 1,
+      trialDays: 0,
+      status: "active",
+      lastSyncedAt: 1000,
+    });
+    await t.mutation(internal.plans.upsertPlan, {
+      epaycoPlanId: "plan_deleted",
+      name: "Deleted",
+      description: "Deleted plan",
+      amount: 20000,
+      currency: "COP",
+      interval: "month",
+      intervalCount: 1,
+      trialDays: 0,
+      status: "deleted",
+      lastSyncedAt: 1000,
+    });
+
+    const activePlans = await t.query(api.plans.listLocalPlans, {
+      status: "active",
+    });
+    expect(activePlans).toHaveLength(1);
+    expect(activePlans[0].name).toBe("Active");
+  });
+});

package/src/component/plans.ts

@@ -0,0 +1,86 @@
+import { v } from "convex/values";
+import { internalMutation, query } from "./_generated/server.js";
+
+/** Local persistence for recurring plans. */
+
+export const getLocalPlan = query({
+  args: { epaycoPlanId: v.string() },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("plans")
+      .withIndex("by_epaycoPlanId", (q) =>
+        q.eq("epaycoPlanId", args.epaycoPlanId),
+      )
+      .first();
+  },
+});
+
+export const listLocalPlans = query({
+  args: { status: v.optional(v.string()), limit: v.optional(v.number()) },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    if (args.status) {
+      return await ctx.db
+        .query("plans")
+        .withIndex("by_status", (q) => q.eq("status", args.status!))
+        .take(args.limit ?? 100);
+    }
+    return await ctx.db.query("plans").take(args.limit ?? 100);
+  },
+});
+
+export const upsertPlan = internalMutation({
+  args: {
+    epaycoPlanId: v.string(),
+    name: v.optional(v.string()),
+    description: v.optional(v.string()),
+    amount: v.optional(v.number()),
+    currency: v.optional(v.string()),
+    interval: v.optional(v.string()),
+    intervalCount: v.optional(v.number()),
+    trialDays: v.optional(v.number()),
+    status: v.optional(v.string()),
+    lastSyncedAt: v.number(),
+  },
+  returns: v.id("plans"),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("plans")
+      .withIndex("by_epaycoPlanId", (q) =>
+        q.eq("epaycoPlanId", args.epaycoPlanId),
+      )
+      .first();
+
+    if (existing) {
+      if (existing.lastSyncedAt >= args.lastSyncedAt) return existing._id;
+
+      const patch: Record<string, unknown> = { lastSyncedAt: args.lastSyncedAt };
+      if (args.name !== undefined) patch.name = args.name;
+      if (args.description !== undefined) patch.description = args.description;
+      if (args.amount !== undefined) patch.amount = args.amount;
+      if (args.currency !== undefined) patch.currency = args.currency;
+      if (args.interval !== undefined) patch.interval = args.interval;
+      if (args.intervalCount !== undefined)
+        patch.intervalCount = args.intervalCount;
+      if (args.trialDays !== undefined) patch.trialDays = args.trialDays;
+      if (args.status !== undefined) patch.status = args.status;
+
+      await ctx.db.patch(existing._id, patch);
+      return existing._id;
+    }
+
+    return await ctx.db.insert("plans", {
+      epaycoPlanId: args.epaycoPlanId,
+      name: args.name ?? "",
+      description: args.description ?? "",
+      amount: args.amount ?? 0,
+      currency: args.currency ?? "COP",
+      interval: args.interval ?? "month",
+      intervalCount: args.intervalCount ?? 1,
+      trialDays: args.trialDays ?? 0,
+      status: args.status ?? "active",
+      lastSyncedAt: args.lastSyncedAt,
+    });
+  },
+});

package/src/component/plansApi.ts

@@ -0,0 +1,135 @@
+import { v } from "convex/values";
+import { action } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import { epaycoCredentialsValidator, planInfoValidator } from "./validators.js";
+import { getEpaycoClient, unwrap } from "./epaycoClient.js";
+
+/** Create a recurring plan. */
+export const createPlan = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    planInfo: planInfoValidator,
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const p = args.planInfo;
+    const epayco = getEpaycoClient(args.credentials);
+    const result = unwrap(
+      await epayco.plans.create({
+        id_plan: p.idPlan,
+        name: p.name,
+        description: p.description,
+        amount: p.amount,
+        currency: p.currency,
+        interval: p.interval,
+        interval_count: p.intervalCount,
+        trial_days: p.trialDays,
+        ...(p.iva !== undefined ? { iva: p.iva } : {}),
+        ...(p.ico !== undefined ? { ico: p.ico } : {}),
+      }),
+    );
+
+    await ctx.runMutation(internal.plans.upsertPlan, {
+      epaycoPlanId: p.idPlan,
+      name: p.name,
+      description: p.description,
+      amount: p.amount,
+      currency: p.currency,
+      interval: p.interval,
+      intervalCount: p.intervalCount,
+      trialDays: p.trialDays,
+      status: "active",
+      lastSyncedAt: Date.now(),
+    });
+
+    return result;
+  },
+});
+
+export const getPlan = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    epaycoPlanId: v.string(),
+  },
+  returns: v.any(),
+  handler: async (_ctx, args) => {
+    const epayco = getEpaycoClient(args.credentials);
+    return unwrap(await epayco.plans.get(args.epaycoPlanId));
+  },
+});
+
+export const listPlans = action({
+  args: { credentials: epaycoCredentialsValidator },
+  returns: v.any(),
+  handler: async (_ctx, args) => {
+    const epayco = getEpaycoClient(args.credentials);
+    return unwrap(await epayco.plans.list());
+  },
+});
+
+export const updatePlan = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    epaycoPlanId: v.string(),
+    name: v.optional(v.string()),
+    description: v.optional(v.string()),
+    amount: v.optional(v.number()),
+    currency: v.optional(v.string()),
+    interval: v.optional(v.string()),
+    intervalCount: v.optional(v.number()),
+    trialDays: v.optional(v.number()),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const epayco = getEpaycoClient(args.credentials);
+    const result = unwrap(
+      await epayco.plans.update(args.epaycoPlanId, {
+        ...(args.name ? { name: args.name } : {}),
+        ...(args.description ? { description: args.description } : {}),
+        ...(args.amount !== undefined ? { amount: args.amount } : {}),
+        ...(args.currency ? { currency: args.currency } : {}),
+        ...(args.interval ? { interval: args.interval } : {}),
+        ...(args.intervalCount !== undefined
+          ? { interval_count: args.intervalCount }
+          : {}),
+        ...(args.trialDays !== undefined ? { trial_days: args.trialDays } : {}),
+      }),
+    );
+
+    await ctx.runMutation(internal.plans.upsertPlan, {
+      epaycoPlanId: args.epaycoPlanId,
+      ...(args.name !== undefined ? { name: args.name } : {}),
+      ...(args.description !== undefined ? { description: args.description } : {}),
+      ...(args.amount !== undefined ? { amount: args.amount } : {}),
+      ...(args.currency !== undefined ? { currency: args.currency } : {}),
+      ...(args.interval !== undefined ? { interval: args.interval } : {}),
+      ...(args.intervalCount !== undefined
+        ? { intervalCount: args.intervalCount }
+        : {}),
+      ...(args.trialDays !== undefined ? { trialDays: args.trialDays } : {}),
+      lastSyncedAt: Date.now(),
+    });
+
+    return result;
+  },
+});
+
+export const deletePlan = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    epaycoPlanId: v.string(),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const epayco = getEpaycoClient(args.credentials);
+    const result = unwrap(await epayco.plans.delete(args.epaycoPlanId));
+
+    await ctx.runMutation(internal.plans.upsertPlan, {
+      epaycoPlanId: args.epaycoPlanId,
+      status: "deleted",
+      lastSyncedAt: Date.now(),
+    });
+
+    return result;
+  },
+});

package/src/component/pseApi.ts

@@ -0,0 +1,125 @@
+import { v } from "convex/values";
+import { action } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import { epaycoCredentialsValidator, pseInfoValidator } from "./validators.js";
+import { getEpaycoClient, unwrap, dataOf, pick } from "./epaycoClient.js";
+import { buildSplitPayload, storedReceivers } from "./payloads.js";
+import { rateLimiter } from "./rateLimits.js";
+
+/** Create a PSE (bank debit) transaction. Returns a `urlbanco` to redirect to. */
+export const createPseTransaction = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    userId: v.string(),
+    pseInfo: pseInfoValidator,
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    await rateLimiter.limit(ctx, "createPseTransaction", {
+      key: args.userId,
+      throws: true,
+    });
+
+    const info = args.pseInfo;
+    const epayco = getEpaycoClient(args.credentials);
+
+    const result = unwrap(
+      await epayco.bank.create({
+        bank: info.bank,
+        invoice: info.bill,
+        description: info.description,
+        value: String(info.value),
+        tax: String(info.tax),
+        tax_base: String(info.taxBase),
+        currency: info.currency ?? "COP",
+        type_person: info.typePerson,
+        doc_type: info.docType,
+        doc_number: info.docNumber,
+        name: info.name,
+        last_name: info.lastName,
+        email: info.email,
+        country: info.country ?? "CO",
+        cell_phone: info.cellPhone,
+        ...(info.ip ? { ip: info.ip } : {}),
+        ...(info.urlResponse ? { url_response: info.urlResponse } : {}),
+        ...(info.urlConfirmation
+          ? { url_confirmation: info.urlConfirmation }
+          : {}),
+        metodoconfirmacion: "GET",
+        extra1: info.extra1 ?? "",
+        extra2: info.extra2 ?? "",
+        extra3: info.extra3 ?? "",
+        ...buildSplitPayload(info.split, true),
+      }),
+    );
+
+    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",
+          "transactionId",
+          "transaction_id",
+        ]),
+        paymentMethod: "pse",
+        status: "pending",
+        amount: info.value,
+        currency: info.currency ?? "COP",
+        description: info.description,
+        customerEmail: info.email,
+        bankName: pick(data, ["bank", "banco"]) ?? info.bank,
+        splitPayment: info.split !== undefined ? true : undefined,
+        splitReceivers: storedReceivers(info.split),
+        rawResponse: data,
+        lastSyncedAt: Date.now(),
+      });
+    }
+
+    return result;
+  },
+});
+
+/** Look up a PSE transaction's current state by its ticket id. */
+export const getPseTransaction = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    ticketId: v.string(),
+  },
+  returns: v.any(),
+  handler: async (_ctx, args) => {
+    const epayco = getEpaycoClient(args.credentials);
+    return unwrap(await epayco.bank.get(args.ticketId));
+  },
+});
+
+/** Fetch the PSE bank list and cache it locally. */
+export const getBanks = action({
+  args: { credentials: epaycoCredentialsValidator },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const epayco = getEpaycoClient(args.credentials);
+    const result = unwrap(await epayco.bank.getBanks());
+
+    const list = Array.isArray(result.data)
+      ? (result.data as Array<Record<string, unknown>>)
+      : [];
+
+    for (const bank of list) {
+      const bankCode = pick(bank, ["bankCode", "code", "value", "pseCode"]);
+      const bankName = pick(bank, ["bankName", "name", "description", "label"]);
+      if (bankCode && bankName) {
+        await ctx.runMutation(internal.banks.upsertBank, {
+          bankCode,
+          bankName,
+          lastSyncedAt: Date.now(),
+        });
+      }
+    }
+
+    return result;
+  },
+});

package/src/component/rateLimits.ts

@@ -0,0 +1,67 @@
+import { RateLimiter, MINUTE } from "@convex-dev/rate-limiter";
+import { components } from "./_generated/api.js";
+
+export const rateLimiter = new RateLimiter(components.rateLimiter, {
+  createCustomer: {
+    kind: "token bucket",
+    rate: 5,
+    period: MINUTE,
+    capacity: 3,
+  },
+  createToken: {
+    kind: "token bucket",
+    rate: 10,
+    period: MINUTE,
+    capacity: 5,
+  },
+  createCharge: {
+    kind: "token bucket",
+    rate: 10,
+    period: MINUTE,
+    capacity: 5,
+  },
+  createSubscription: {
+    kind: "token bucket",
+    rate: 5,
+    period: MINUTE,
+    capacity: 3,
+  },
+  createPseTransaction: {
+    kind: "token bucket",
+    rate: 10,
+    period: MINUTE,
+    capacity: 5,
+  },
+  createCashPayment: {
+    kind: "token bucket",
+    rate: 10,
+    period: MINUTE,
+    capacity: 5,
+  },
+  createDaviplataPayment: {
+    kind: "token bucket",
+    rate: 10,
+    period: MINUTE,
+    capacity: 5,
+  },
+  // Keyed per ref_payco: caps OTP brute-force attempts on a single payment.
+  confirmDaviplataPayment: {
+    kind: "token bucket",
+    rate: 5,
+    period: MINUTE,
+    capacity: 5,
+  },
+  createSafetyPayPayment: {
+    kind: "token bucket",
+    rate: 10,
+    period: MINUTE,
+    capacity: 5,
+  },
+  chargeSubscription: {
+    kind: "token bucket",
+    rate: 5,
+    period: MINUTE,
+    capacity: 3,
+  },
+  webhookProcessing: { kind: "fixed window", rate: 200, period: MINUTE },
+});

package/src/component/safetypayApi.ts

@@ -0,0 +1,78 @@
+import { v } from "convex/values";
+import { action } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import {
+  epaycoCredentialsValidator,
+  safetypayInfoValidator,
+} from "./validators.js";
+import { getEpaycoClient, unwrap, dataOf, pick } from "./epaycoClient.js";
+import { rateLimiter } from "./rateLimits.js";
+
+/** Create a SafetyPay transaction (cash or online bank). */
+export const createSafetyPayPayment = action({
+  args: {
+    credentials: epaycoCredentialsValidator,
+    userId: v.string(),
+    safetypayInfo: safetypayInfoValidator,
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    await rateLimiter.limit(ctx, "createSafetyPayPayment", {
+      key: args.userId,
+      throws: true,
+    });
+
+    const info = args.safetypayInfo;
+    const epayco = getEpaycoClient(args.credentials);
+
+    const result = unwrap(
+      await epayco.safetypay.create({
+        cash: info.cash,
+        ...(info.endDate ? { end_date: info.endDate } : {}),
+        doc_type: info.docType,
+        doc_number: info.docNumber,
+        name: info.name,
+        last_name: info.lastName,
+        email: info.email,
+        ind_country: info.indCountry ?? "57",
+        phone: info.phone,
+        country: info.country ?? "CO",
+        ...(info.invoice ? { invoice: info.invoice } : {}),
+        ...(info.city ? { city: info.city } : {}),
+        ...(info.address ? { address: info.address } : {}),
+        ...(info.ip ? { ip: info.ip } : {}),
+        currency: info.currency ?? "COP",
+        description: info.description,
+        value: info.value,
+        tax: info.tax,
+        ico: info.ico ?? 0,
+        tax_base: info.taxBase,
+        method_confirmation: info.methodConfirmation ?? "",
+        ...(info.urlConfirmation
+          ? { url_confirmation: info.urlConfirmation }
+          : {}),
+      }),
+    );
+
+    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"]),
+        paymentMethod: "safetypay",
+        status: "pending",
+        amount: info.value,
+        currency: info.currency ?? "COP",
+        description: info.description,
+        customerEmail: info.email,
+        rawResponse: data,
+        lastSyncedAt: Date.now(),
+      });
+    }
+
+    return result;
+  },
+});