@abdssamie/adyen-payments 0.1.0

package/src/component/_generated/server.ts

@@ -0,0 +1,156 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/convex.config.ts

@@ -0,0 +1,3 @@
+import { defineComponent } from "convex/server";
+
+export default defineComponent("adyenPayments");

package/src/component/private.ts

@@ -0,0 +1,277 @@
+import { v } from "convex/values";
+import { mutation } from "./_generated/server.js";
+
+/**
+ * Record a newly created checkout session.
+ */
+export const insertCheckoutSession = mutation({
+  args: {
+    sessionId: v.string(),
+    sessionData: v.string(),
+    shopperReference: v.optional(v.string()),
+    merchantReference: v.string(),
+    amount: v.number(),
+    currency: v.string(),
+    url: v.optional(v.string()),
+    autoCapture: v.optional(v.boolean()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("checkout_sessions")
+      .withIndex("by_session_id", (q) => q.eq("sessionId", args.sessionId))
+      .unique();
+
+    if (!existing) {
+      await ctx.db.insert("checkout_sessions", {
+        sessionId: args.sessionId,
+        sessionData: args.sessionData,
+        shopperReference: args.shopperReference,
+        merchantReference: args.merchantReference,
+        status: "active",
+        amount: args.amount,
+        currency: args.currency,
+        url: args.url,
+        autoCapture: args.autoCapture,
+      });
+    }
+    return null;
+  },
+});
+
+/**
+ * Record a payment transaction (e.g. authorization success/failure).
+ */
+export const recordPayment = mutation({
+  args: {
+    pspReference: v.string(),
+    originalReference: v.optional(v.string()),
+    shopperReference: v.optional(v.string()),
+    merchantReference: v.string(),
+    amount: v.number(),
+    currency: v.string(),
+    status: v.string(),
+    paymentMethod: v.optional(v.string()),
+    userId: v.optional(v.string()),
+    orgId: v.optional(v.string()),
+    metadata: v.optional(v.any()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("payments")
+      .withIndex("by_psp_reference", (q) =>
+        q.eq("pspReference", args.pspReference)
+      )
+      .unique();
+
+    if (!existing) {
+      await ctx.db.insert("payments", {
+        pspReference: args.pspReference,
+        originalReference: args.originalReference,
+        shopperReference: args.shopperReference,
+        merchantReference: args.merchantReference,
+        amount: args.amount,
+        currency: args.currency,
+        status: args.status,
+        paymentMethod: args.paymentMethod,
+        created: Date.now(),
+        userId: args.userId,
+        orgId: args.orgId,
+        metadata: args.metadata,
+      });
+    } else {
+      await ctx.db.patch("payments", existing._id, {
+        status: args.status,
+        ...(args.shopperReference !== undefined && { shopperReference: args.shopperReference }),
+        ...(args.userId !== undefined && { userId: args.userId }),
+        ...(args.orgId !== undefined && { orgId: args.orgId }),
+        ...(args.metadata !== undefined && { metadata: args.metadata }),
+      });
+    }
+    return null;
+  },
+});
+
+/**
+ * Update the status of a payment transaction (e.g. captured, refunded, cancelled).
+ */
+export const updatePaymentStatus = mutation({
+  args: {
+    pspReference: v.string(),
+    status: v.string(),
+    originalReference: v.optional(v.string()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const payment = await ctx.db
+      .query("payments")
+      .withIndex("by_psp_reference", (q) =>
+        q.eq("pspReference", args.pspReference)
+      )
+      .unique();
+
+    if (payment) {
+      await ctx.db.patch("payments", payment._id, {
+        status: args.status,
+        ...(args.originalReference !== undefined && { originalReference: args.originalReference }),
+      });
+    } else {
+      // If payment is not found locally, create a placeholder payment that will be backfilled/updated.
+      // (This handles cases where captures/refunds are triggered but original auth record is not in db)
+      await ctx.db.insert("payments", {
+        pspReference: args.pspReference,
+        originalReference: args.originalReference,
+        merchantReference: "unknown",
+        amount: 0,
+        currency: "unknown",
+        status: args.status,
+        created: Date.now(),
+      });
+    }
+    return null;
+  },
+});
+
+/**
+ * Insert or update a single tokenized payment method.
+ */
+export const insertPaymentMethod = mutation({
+  args: {
+    shopperReference: v.string(),
+    recurringDetailReference: v.string(),
+    variant: v.string(),
+    cardLast4: v.optional(v.string()),
+    cardExpiryMonth: v.optional(v.string()),
+    cardExpiryYear: v.optional(v.string()),
+    metadata: v.optional(v.any()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("payment_methods")
+      .withIndex("by_recurring_detail_reference", (q) =>
+        q.eq("recurringDetailReference", args.recurringDetailReference)
+      )
+      .unique();
+
+    if (existing) {
+      await ctx.db.patch("payment_methods", existing._id, {
+        status: "active",
+        variant: args.variant,
+        cardLast4: args.cardLast4,
+        cardExpiryMonth: args.cardExpiryMonth,
+        cardExpiryYear: args.cardExpiryYear,
+        ...(args.metadata !== undefined && { metadata: args.metadata }),
+      });
+    } else {
+      await ctx.db.insert("payment_methods", {
+        shopperReference: args.shopperReference,
+        recurringDetailReference: args.recurringDetailReference,
+        variant: args.variant,
+        cardLast4: args.cardLast4,
+        cardExpiryMonth: args.cardExpiryMonth,
+        cardExpiryYear: args.cardExpiryYear,
+        status: "active",
+        metadata: args.metadata,
+      });
+    }
+    return null;
+  },
+});
+
+/**
+ * Synchronize the active stored card/payment method tokens for a shopper.
+ */
+export const syncPaymentMethods = mutation({
+  args: {
+    shopperReference: v.string(),
+    paymentMethods: v.array(
+      v.object({
+        recurringDetailReference: v.string(),
+        variant: v.string(),
+        cardLast4: v.optional(v.string()),
+        cardExpiryMonth: v.optional(v.string()),
+        cardExpiryYear: v.optional(v.string()),
+        metadata: v.optional(v.any()),
+      })
+    ),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    // Get all existing payment methods for the shopper
+    const existing = await ctx.db
+      .query("payment_methods")
+      .withIndex("by_shopper_reference", (q) =>
+        q.eq("shopperReference", args.shopperReference)
+      )
+      .collect();
+
+    const incomingRefs = new Set(
+      args.paymentMethods.map((m) => m.recurringDetailReference)
+    );
+
+    // Mark methods that are no longer active as disabled
+    for (const method of existing) {
+      if (
+        !incomingRefs.has(method.recurringDetailReference) &&
+        method.status !== "disabled"
+      ) {
+        await ctx.db.patch("payment_methods", method._id, { status: "disabled" });
+      }
+    }
+
+    // Insert or update incoming active methods
+    for (const method of args.paymentMethods) {
+      const match = existing.find(
+        (m) => m.recurringDetailReference === method.recurringDetailReference
+      );
+      if (match) {
+        await ctx.db.patch("payment_methods", match._id, {
+          status: "active",
+          variant: method.variant,
+          cardLast4: method.cardLast4,
+          cardExpiryMonth: method.cardExpiryMonth,
+          cardExpiryYear: method.cardExpiryYear,
+          ...(method.metadata !== undefined && { metadata: method.metadata }),
+        });
+      } else {
+        await ctx.db.insert("payment_methods", {
+          shopperReference: args.shopperReference,
+          recurringDetailReference: method.recurringDetailReference,
+          variant: method.variant,
+          cardLast4: method.cardLast4,
+          cardExpiryMonth: method.cardExpiryMonth,
+          cardExpiryYear: method.cardExpiryYear,
+          status: "active",
+          metadata: method.metadata,
+        });
+      }
+    }
+    return null;
+  },
+});
+
+/**
+ * Update the status of a checkout session.
+ */
+export const updateCheckoutSessionStatus = mutation({
+  args: {
+    merchantReference: v.string(),
+    status: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const session = await ctx.db
+      .query("checkout_sessions")
+      .withIndex("by_merchant_reference", (q) =>
+        q.eq("merchantReference", args.merchantReference)
+      )
+      .unique();
+
+    if (session) {
+      await ctx.db.patch("checkout_sessions", session._id, { status: args.status });
+    }
+    return null;
+  },
+});

package/src/component/public.test.ts

@@ -0,0 +1,92 @@
+import { test, expect } from "vitest";
+import { initConvexTest } from "./setup.test.js";
+import { api } from "./_generated/api.js";
+
+test("shopper operations", async () => {
+  const t = initConvexTest();
+
+  // Create a shopper
+  const shopperRef = await t.mutation(api.public.createOrUpdateShopper, {
+    shopperReference: "user_123",
+    email: "test@example.com",
+    name: "Test User",
+    userId: "user_123",
+    metadata: { plan: "pro" },
+  });
+  expect(shopperRef).toBe("user_123");
+
+  // Get shopper by shopperReference
+  const shopper = await t.query(api.public.getShopper, {
+    shopperReference: "user_123",
+  });
+  expect(shopper).not.toBeNull();
+  expect(shopper!.email).toBe("test@example.com");
+  expect(shopper!.userId).toBe("user_123");
+
+  // Get shopper by userId
+  const shopperByUserId = await t.query(api.public.getShopperByUserId, {
+    userId: "user_123",
+  });
+  expect(shopperByUserId).not.toBeNull();
+  expect(shopperByUserId!.shopperReference).toBe("user_123");
+
+  // Get shopper by email
+  const shopperByEmail = await t.query(api.public.getShopperByEmail, {
+    email: "test@example.com",
+  });
+  expect(shopperByEmail).not.toBeNull();
+  expect(shopperByEmail!.shopperReference).toBe("user_123");
+});
+
+test("checkout session operations", async () => {
+  const t = initConvexTest();
+
+  await t.mutation(api.private.insertCheckoutSession, {
+    sessionId: "sess_123",
+    sessionData: "data_blob",
+    shopperReference: "user_123",
+    merchantReference: "ref_123",
+    amount: 1000,
+    currency: "EUR",
+    url: "https://checkout.adyen.com/pay",
+  });
+
+  const session = await t.query(api.public.getCheckoutSession, {
+    sessionId: "sess_123",
+  });
+  expect(session).not.toBeNull();
+  expect(session!.amount).toBe(1000);
+  expect(session!.url).toBe("https://checkout.adyen.com/pay");
+});
+
+test("payment operations", async () => {
+  const t = initConvexTest();
+
+  await t.mutation(api.private.recordPayment, {
+    pspReference: "psp_123",
+    shopperReference: "user_123",
+    merchantReference: "ref_123",
+    amount: 2500,
+    currency: "USD",
+    status: "authorised",
+    paymentMethod: "visa",
+  });
+
+  const payment = await t.query(api.public.getPayment, {
+    pspReference: "psp_123",
+  });
+  expect(payment).not.toBeNull();
+  expect(payment!.amount).toBe(2500);
+  expect(payment!.status).toBe("authorised");
+
+  // Update status
+  await t.mutation(api.private.updatePaymentStatus, {
+    pspReference: "psp_123",
+    status: "captured",
+  });
+
+  const updated = await t.query(api.public.getPayment, {
+    pspReference: "psp_123",
+  });
+  expect(updated!.status).toBe("captured");
+});