convex-paystack 0.0.1

package/src/component/lib.ts

@@ -0,0 +1,278 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+
+const transactionStatusValidator = v.union(
+  v.literal("pending"),
+  v.literal("success"),
+  v.literal("failed"),
+  v.literal("abandoned"),
+);
+
+const subscriptionStatusValidator = v.union(
+  v.literal("active"),
+  v.literal("non-renewing"),
+  v.literal("attention"),
+  v.literal("completed"),
+  v.literal("cancelled"),
+);
+
+const transactionValidator = v.object({
+  _id: v.id("transactions"),
+  _creationTime: v.number(),
+  reference: v.string(),
+  customerEmail: v.string(),
+  amount: v.number(),
+  currency: v.string(),
+  status: transactionStatusValidator,
+  channel: v.optional(v.string()),
+  gatewayResponse: v.optional(v.string()),
+  authorizationCode: v.optional(v.string()),
+  paidAt: v.optional(v.number()),
+  metadata: v.optional(v.string()),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+});
+
+const subscriptionValidator = v.object({
+  _id: v.id("subscriptions"),
+  _creationTime: v.number(),
+  subscriptionCode: v.string(),
+  emailToken: v.optional(v.string()),
+  customerEmail: v.string(),
+  customerCode: v.optional(v.string()),
+  planCode: v.string(),
+  status: subscriptionStatusValidator,
+  amount: v.optional(v.number()),
+  nextPaymentDate: v.optional(v.number()),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+});
+
+const webhookEventValidator = v.object({
+  _id: v.id("webhookEvents"),
+  _creationTime: v.number(),
+  eventId: v.string(),
+  eventType: v.string(),
+  reference: v.optional(v.string()),
+  payload: v.string(),
+  receivedAt: v.number(),
+});
+
+// ─── Queries ────────────────────────────────────────────────────────────────
+
+export const getTransaction = query({
+  args: { reference: v.string() },
+  returns: v.union(v.null(), transactionValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("transactions")
+      .withIndex("by_reference", (q) => q.eq("reference", args.reference))
+      .first();
+  },
+});
+
+export const listTransactions = query({
+  args: { customerEmail: v.string(), limit: v.optional(v.number()) },
+  returns: v.array(transactionValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("transactions")
+      .withIndex("by_customerEmail", (q) => q.eq("customerEmail", args.customerEmail))
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});
+
+export const getSubscription = query({
+  args: { subscriptionCode: v.string() },
+  returns: v.union(v.null(), subscriptionValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("subscriptions")
+      .withIndex("by_subscriptionCode", (q) =>
+        q.eq("subscriptionCode", args.subscriptionCode),
+      )
+      .first();
+  },
+});
+
+export const listSubscriptions = query({
+  args: { customerEmail: v.string() },
+  returns: v.array(subscriptionValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("subscriptions")
+      .withIndex("by_customerEmail", (q) => q.eq("customerEmail", args.customerEmail))
+      .order("desc")
+      .collect();
+  },
+});
+
+export const hasActiveSubscription = query({
+  args: { customerEmail: v.string() },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const sub = await ctx.db
+      .query("subscriptions")
+      .withIndex("by_customerEmail", (q) => q.eq("customerEmail", args.customerEmail))
+      .order("desc")
+      .first();
+    return sub?.status === "active" || sub?.status === "non-renewing";
+  },
+});
+
+/**
+ * Reads the raw webhook event log, newest first — useful for an audit
+ * trail or a live "what just happened" console in your own app. Every
+ * event Paystack has ever sent to this component's webhook handler is
+ * recorded here for idempotency, whether or not it triggered a state
+ * change.
+ */
+export const listRecentEvents = query({
+  args: { limit: v.optional(v.number()) },
+  returns: v.array(webhookEventValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("webhookEvents")
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});
+
+/**
+ * Aggregate row counts across all three tables — enough for a small
+ * dashboard stat row. This does a full table scan, so it's fine for the
+ * data volumes a demo or small integration produces; a high-volume
+ * production app should track its own counters instead of calling this
+ * on every render.
+ */
+export const getStats = query({
+  args: {},
+  returns: v.object({
+    transactions: v.number(),
+    subscriptions: v.number(),
+    events: v.number(),
+  }),
+  handler: async (ctx) => {
+    const [transactions, subscriptions, events] = await Promise.all([
+      ctx.db.query("transactions").collect(),
+      ctx.db.query("subscriptions").collect(),
+      ctx.db.query("webhookEvents").collect(),
+    ]);
+    return {
+      transactions: transactions.length,
+      subscriptions: subscriptions.length,
+      events: events.length,
+    };
+  },
+});
+
+// ─── Mutations ──────────────────────────────────────────────────────────────
+
+export const recordTransaction = mutation({
+  args: {
+    reference: v.string(),
+    customerEmail: v.string(),
+    amount: v.number(),
+    currency: v.string(),
+    status: transactionStatusValidator,
+    channel: v.optional(v.string()),
+    gatewayResponse: v.optional(v.string()),
+    authorizationCode: v.optional(v.string()),
+    paidAt: v.optional(v.number()),
+    metadata: v.optional(v.string()),
+  },
+  returns: v.id("transactions"),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const existing = await ctx.db
+      .query("transactions")
+      .withIndex("by_reference", (q) => q.eq("reference", args.reference))
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, { ...args, updatedAt: now });
+      return existing._id;
+    }
+
+    return await ctx.db.insert("transactions", {
+      ...args,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+export const recordSubscriptionEvent = mutation({
+  args: {
+    subscriptionCode: v.string(),
+    emailToken: v.optional(v.string()),
+    customerEmail: v.string(),
+    customerCode: v.optional(v.string()),
+    planCode: v.string(),
+    status: subscriptionStatusValidator,
+    amount: v.optional(v.number()),
+    nextPaymentDate: v.optional(v.number()),
+  },
+  returns: v.id("subscriptions"),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const existing = await ctx.db
+      .query("subscriptions")
+      .withIndex("by_subscriptionCode", (q) =>
+        q.eq("subscriptionCode", args.subscriptionCode),
+      )
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, { ...args, updatedAt: now });
+      return existing._id;
+    }
+
+    return await ctx.db.insert("subscriptions", {
+      ...args,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+export const updateSubscriptionStatus = mutation({
+  args: {
+    subscriptionCode: v.string(),
+    status: subscriptionStatusValidator,
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("subscriptions")
+      .withIndex("by_subscriptionCode", (q) =>
+        q.eq("subscriptionCode", args.subscriptionCode),
+      )
+      .first();
+    if (!existing) return null;
+    await ctx.db.patch(existing._id, { status: args.status, updatedAt: Date.now() });
+    return null;
+  },
+});
+
+export const checkAndRecordEvent = mutation({
+  args: {
+    eventId: v.string(),
+    eventType: v.string(),
+    reference: v.optional(v.string()),
+    payload: v.string(),
+  },
+  returns: v.object({ alreadyProcessed: v.boolean() }),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("webhookEvents")
+      .withIndex("by_eventId", (q) => q.eq("eventId", args.eventId))
+      .first();
+    if (existing) {
+      return { alreadyProcessed: true };
+    }
+    await ctx.db.insert("webhookEvents", { ...args, receivedAt: Date.now() });
+    return { alreadyProcessed: false };
+  },
+});

package/src/component/schema.ts

@@ -0,0 +1,58 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  transactions: defineTable({
+    reference: v.string(),
+    customerEmail: v.string(),
+    amount: v.number(),
+    currency: v.string(),
+    status: v.union(
+      v.literal("pending"),
+      v.literal("success"),
+      v.literal("failed"),
+      v.literal("abandoned"),
+    ),
+    channel: v.optional(v.string()),
+    gatewayResponse: v.optional(v.string()),
+    authorizationCode: v.optional(v.string()),
+    paidAt: v.optional(v.number()),
+    metadata: v.optional(v.string()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_reference", ["reference"])
+    .index("by_customerEmail", ["customerEmail"]),
+
+  subscriptions: defineTable({
+    subscriptionCode: v.string(),
+    emailToken: v.optional(v.string()),
+    customerEmail: v.string(),
+    customerCode: v.optional(v.string()),
+    planCode: v.string(),
+    status: v.union(
+      v.literal("active"),
+      v.literal("non-renewing"),
+      v.literal("attention"),
+      v.literal("completed"),
+      v.literal("cancelled"),
+    ),
+    amount: v.optional(v.number()),
+    nextPaymentDate: v.optional(v.number()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_subscriptionCode", ["subscriptionCode"])
+    .index("by_customerEmail", ["customerEmail"])
+    .index("by_status", ["status"]),
+
+  webhookEvents: defineTable({
+    eventId: v.string(),
+    eventType: v.string(),
+    reference: v.optional(v.string()),
+    payload: v.string(),
+    receivedAt: v.number(),
+  })
+    .index("by_eventId", ["eventId"])
+    .index("by_eventType", ["eventType"]),
+});

package/src/component/setup.test.ts

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

package/src/test.ts

@@ -0,0 +1,18 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "convexPaystack",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };