alepha 0.19.2 → 0.19.4

package/src/{billing → api/payments}/__tests__/PaymentMethodService.spec.ts

@@ -2,7 +2,8 @@ import { randomUUID } from "node:crypto";
 import { Alepha } from "alepha";
 import { AlephaOrmPostgres } from "alepha/orm/postgres";
 import { describe, it } from "vitest";
-import { AlephaBilling } from "../index.ts";
+import { PaymentError } from "../errors/PaymentError.ts";
+import { AlephaApiPayments } from "../index.ts";
 import { PaymentMethodService } from "../services/PaymentMethodService.ts";
 
 describe("PaymentMethodService", () => {
@@ -10,7 +11,9 @@ describe("PaymentMethodService", () => {
   const userId2 = randomUUID();
   const orgId = randomUUID();
   it("should add a payment method", async ({ expect }) => {
-    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const alepha = Alepha.create()
+      .with(AlephaOrmPostgres)
+      .with(AlephaApiPayments);
     const service = alepha.inject(PaymentMethodService);
     await alepha.start();
 
@@ -21,7 +24,9 @@ describe("PaymentMethodService", () => {
   });
 
   it("should list payment methods for a user", async ({ expect }) => {
-    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const alepha = Alepha.create()
+      .with(AlephaOrmPostgres)
+      .with(AlephaApiPayments);
     const service = alepha.inject(PaymentMethodService);
     await alepha.start();
 
@@ -33,7 +38,9 @@ describe("PaymentMethodService", () => {
   });
 
   it("should remove a payment method", async ({ expect }) => {
-    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const alepha = Alepha.create()
+      .with(AlephaOrmPostgres)
+      .with(AlephaApiPayments);
     const service = alepha.inject(PaymentMethodService);
     await alepha.start();
 
@@ -45,7 +52,9 @@ describe("PaymentMethodService", () => {
   });
 
   it("should set a default payment method", async ({ expect }) => {
-    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const alepha = Alepha.create()
+      .with(AlephaOrmPostgres)
+      .with(AlephaApiPayments);
     const service = alepha.inject(PaymentMethodService);
     await alepha.start();
 
@@ -66,7 +75,9 @@ describe("PaymentMethodService", () => {
   it("should reject removing another user's payment method", async ({
     expect,
   }) => {
-    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const alepha = Alepha.create()
+      .with(AlephaOrmPostgres)
+      .with(AlephaApiPayments);
     const service = alepha.inject(PaymentMethodService);
     await alepha.start();
 
@@ -75,4 +86,19 @@ describe("PaymentMethodService", () => {
       service.removePaymentMethod(method.id, userId2),
     ).rejects.toThrowError();
   });
+
+  it("should reject setting default for another user's payment method", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create()
+      .with(AlephaOrmPostgres)
+      .with(AlephaApiPayments);
+    const service = alepha.inject(PaymentMethodService);
+    await alepha.start();
+
+    const method = await service.addPaymentMethod(userId, orgId, "tok_visa");
+    await expect(service.setDefault(method.id, userId2)).rejects.toThrowError(
+      PaymentError,
+    );
+  });
 });

package/src/api/payments/__tests__/PaymentService.spec.ts

@@ -0,0 +1,279 @@
+import { randomUUID } from "node:crypto";
+import { Alepha } from "alepha";
+import { AlephaOrmPostgres } from "alepha/orm/postgres";
+import { describe, it } from "vitest";
+import { PaymentError } from "../errors/PaymentError.ts";
+import { AlephaApiPayments } from "../index.ts";
+import { PaymentService } from "../services/PaymentService.ts";
+
+const setup = async () => {
+  const alepha = Alepha.create()
+    .with(AlephaOrmPostgres)
+    .with(AlephaApiPayments);
+  const payments = alepha.inject(PaymentService);
+  await alepha.start();
+  return { alepha, payments };
+};
+
+describe("PaymentService", () => {
+  it("should create an intent in 'created' status", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    expect(intent.amount).toBe(1500);
+    expect(intent.currency).toBe("eur");
+    expect(intent.status).toBe("created");
+  });
+
+  it("should create a session and transition to 'processing'", async ({
+    expect,
+  }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    const session = await payments.createSession(
+      intent.id,
+      "https://example.com/return",
+    );
+
+    expect(session.url).toContain("/payments/mock-checkout/");
+    expect(session.intentId).toBe(intent.id);
+  });
+
+  it("should capture an authorized intent", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await payments.createSession(intent.id, "https://example.com", true);
+    await payments.handleWebhookEvent(intent.id, "authorized");
+
+    const captured = await payments.capture(intent.id);
+    expect(captured.status).toBe("captured");
+  });
+
+  it("should void an authorized intent", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await payments.createSession(intent.id, "https://example.com", true);
+    await payments.handleWebhookEvent(intent.id, "authorized");
+
+    const voided = await payments.void(intent.id);
+    expect(voided.status).toBe("voided");
+  });
+
+  it("should refund a captured intent", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await payments.createSession(intent.id, "https://example.com");
+    await payments.handleWebhookEvent(intent.id, "captured");
+
+    const refund = await payments.refund(intent.id, 500, "Customer request");
+    expect(refund.amount).toBe(500);
+    expect(refund.status).toBe("completed");
+  });
+
+  it("should record a cash payment directly as captured", async ({
+    expect,
+  }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.recordCashPayment(1500, "eur", {
+      orderId: "order-1",
+    });
+    expect(intent.status).toBe("captured");
+    expect(intent.metadata).toEqual({ orderId: "order-1" });
+  });
+
+  it("should cancel a created intent", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    const cancelled = await payments.cancel(intent.id);
+    expect(cancelled.status).toBe("cancelled");
+  });
+
+  it("should reject capture from wrong status", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await expect(payments.capture(intent.id)).rejects.toThrowError();
+  });
+
+  it("should reject refund from wrong status", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await expect(payments.refund(intent.id, 500)).rejects.toThrowError();
+  });
+
+  it("should reject void from wrong status", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await expect(payments.void(intent.id)).rejects.toThrowError();
+  });
+
+  it("should reject cancel from wrong status", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await payments.createSession(intent.id, "https://example.com");
+    await expect(payments.cancel(intent.id)).rejects.toThrowError();
+  });
+
+  it("should reject capture amount exceeding authorized amount", async ({
+    expect,
+  }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await payments.createSession(intent.id, "https://example.com", true);
+    await payments.handleWebhookEvent(intent.id, "authorized");
+
+    await expect(payments.capture(intent.id, 5000)).rejects.toThrowError(
+      PaymentError,
+    );
+  });
+
+  it("should reject refund exceeding captured amount", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await payments.createSession(intent.id, "https://example.com");
+    await payments.handleWebhookEvent(intent.id, "captured");
+
+    await expect(payments.refund(intent.id, 5000)).rejects.toThrowError(
+      PaymentError,
+    );
+  });
+
+  it("should allow multiple partial refunds up to captured amount", async ({
+    expect,
+  }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await payments.createSession(intent.id, "https://example.com");
+    await payments.handleWebhookEvent(intent.id, "captured");
+
+    await payments.refund(intent.id, 500);
+    const after1 = await payments.getIntent(intent.id);
+    expect(after1.status).toBe("partially_refunded");
+
+    await payments.refund(intent.id, 500);
+    const after2 = await payments.getIntent(intent.id);
+    expect(after2.status).toBe("partially_refunded");
+
+    await payments.refund(intent.id, 500);
+    const after3 = await payments.getIntent(intent.id);
+    expect(after3.status).toBe("refunded");
+  });
+
+  it("should reject refund that would exceed remaining amount", async ({
+    expect,
+  }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await payments.createSession(intent.id, "https://example.com");
+    await payments.handleWebhookEvent(intent.id, "captured");
+
+    await payments.refund(intent.id, 1000);
+
+    await expect(payments.refund(intent.id, 1000)).rejects.toThrowError(
+      PaymentError,
+    );
+  });
+
+  it("should ignore webhook that would downgrade status", async ({
+    expect,
+  }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await payments.createSession(intent.id, "https://example.com");
+    await payments.handleWebhookEvent(intent.id, "captured");
+
+    await payments.handleWebhookEvent(intent.id, "authorized");
+
+    const current = await payments.getIntent(intent.id);
+    expect(current.status).toBe("captured");
+  });
+
+  it("should ignore duplicate webhook for same status", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+    await payments.createSession(intent.id, "https://example.com", true);
+    await payments.handleWebhookEvent(intent.id, "authorized");
+
+    await payments.handleWebhookEvent(intent.id, "authorized");
+
+    const current = await payments.getIntent(intent.id);
+    expect(current.status).toBe("authorized");
+  });
+
+  it("should normalize currency to lowercase", async ({ expect }) => {
+    const { payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "EUR");
+    expect(intent.currency).toBe("eur");
+  });
+
+  it("should emit payments:cancelled event on cancel", async ({ expect }) => {
+    const { alepha, payments } = await setup();
+
+    const intent = await payments.createIntent(1500, "eur");
+
+    let emitted: unknown = null;
+    alepha.events.on("payments:cancelled", (payload: unknown) => {
+      emitted = payload;
+    });
+
+    await payments.cancel(intent.id);
+
+    expect(emitted).toEqual({
+      intentId: intent.id,
+      amount: 1500,
+      currency: "eur",
+      metadata: intent.metadata,
+    });
+  });
+
+  it("should reject checkout for intent belonging to another user", async ({
+    expect,
+  }) => {
+    const { payments } = await setup();
+
+    const userA = randomUUID();
+    const userB = randomUUID();
+    const intent = await payments.createIntent(1500, "eur", undefined, {
+      userId: userA,
+    });
+
+    await expect(
+      payments.createSession(intent.id, "https://example.com", false, userB),
+    ).rejects.toThrowError(PaymentError);
+  });
+
+  it("should set userId on intent during checkout if not already set", async ({
+    expect,
+  }) => {
+    const { payments } = await setup();
+
+    const userX = randomUUID();
+    const intent = await payments.createIntent(1500, "eur");
+
+    await payments.createSession(
+      intent.id,
+      "https://example.com",
+      false,
+      userX,
+    );
+
+    const updated = await payments.getIntent(intent.id);
+    expect(updated.userId).toBe(userX);
+  });
+});

package/src/{billing/controllers/AdminBillingController.ts → api/payments/controllers/AdminPaymentController.ts}

@@ -9,12 +9,12 @@ import {
   refundIntentSchema,
 } from "../schemas/intentSchemas.ts";
 import { refundResourceSchema } from "../schemas/refundSchemas.ts";
-import { BillingService } from "../services/BillingService.ts";
+import { PaymentService } from "../services/PaymentService.ts";
 
-export class AdminBillingController {
-  protected readonly url = "/admin/billing";
-  protected readonly group = "admin:billing";
-  protected readonly billing = $inject(BillingService);
+export class AdminPaymentController {
+  protected readonly url = "/admin/payments";
+  protected readonly group = "admin:payments";
+  protected readonly payments = $inject(PaymentService);
 
   /**
    * List payment intents with pagination and filtering.
@@ -22,13 +22,13 @@ export class AdminBillingController {
   public readonly listIntents = $action({
     path: `${this.url}/intents`,
     group: this.group,
-    use: [$secure({ permissions: ["billing:read"] })],
+    use: [$secure({ permissions: ["payments:read"] })],
     description: "List payment intents",
     schema: {
       query: intentQuerySchema,
       response: t.page(intentResourceSchema),
     },
-    handler: ({ query }) => this.billing.findIntents(query),
+    handler: ({ query }) => this.payments.findIntents(query),
   });
 
   /**
@@ -37,13 +37,13 @@ export class AdminBillingController {
   public readonly getIntent = $action({
     path: `${this.url}/intents/:id`,
     group: this.group,
-    use: [$secure({ permissions: ["billing:read"] })],
+    use: [$secure({ permissions: ["payments:read"] })],
     description: "Get payment intent details",
     schema: {
       params: t.object({ id: t.uuid() }),
       response: intentResourceSchema,
     },
-    handler: ({ params }) => this.billing.getIntent(params.id),
+    handler: ({ params }) => this.payments.getIntent(params.id),
   });
 
   /**
@@ -53,14 +53,15 @@ export class AdminBillingController {
     method: "POST",
     path: `${this.url}/intents/:id/capture`,
     group: this.group,
-    use: [$secure({ permissions: ["billing:write"] })],
+    use: [$secure({ permissions: ["payments:write"] })],
     description: "Capture an authorized payment intent",
     schema: {
       params: t.object({ id: t.uuid() }),
       body: captureIntentSchema,
       response: intentResourceSchema,
     },
-    handler: ({ params, body }) => this.billing.capture(params.id, body.amount),
+    handler: ({ params, body }) =>
+      this.payments.capture(params.id, body.amount),
   });
 
   /**
@@ -70,13 +71,13 @@ export class AdminBillingController {
     method: "POST",
     path: `${this.url}/intents/:id/void`,
     group: this.group,
-    use: [$secure({ permissions: ["billing:write"] })],
+    use: [$secure({ permissions: ["payments:write"] })],
     description: "Void an authorized payment intent",
     schema: {
       params: t.object({ id: t.uuid() }),
       response: intentResourceSchema,
     },
-    handler: ({ params }) => this.billing.void(params.id),
+    handler: ({ params }) => this.payments.void(params.id),
   });
 
   /**
@@ -86,7 +87,7 @@ export class AdminBillingController {
     method: "POST",
     path: `${this.url}/intents/:id/refund`,
     group: this.group,
-    use: [$secure({ permissions: ["billing:write"] })],
+    use: [$secure({ permissions: ["payments:write"] })],
     description: "Issue partial or full refund",
     schema: {
       params: t.object({ id: t.uuid() }),
@@ -94,7 +95,7 @@ export class AdminBillingController {
       response: refundResourceSchema,
     },
     handler: ({ params, body }) =>
-      this.billing.refund(params.id, body.amount, body.reason),
+      this.payments.refund(params.id, body.amount, body.reason),
   });
 
   /**
@@ -104,13 +105,13 @@ export class AdminBillingController {
     method: "POST",
     path: `${this.url}/intents/:id/cancel`,
     group: this.group,
-    use: [$secure({ permissions: ["billing:write"] })],
+    use: [$secure({ permissions: ["payments:write"] })],
     description: "Cancel a created payment intent",
     schema: {
       params: t.object({ id: t.uuid() }),
       response: intentResourceSchema,
     },
-    handler: ({ params }) => this.billing.cancel(params.id),
+    handler: ({ params }) => this.payments.cancel(params.id),
   });
 
   /**
@@ -120,14 +121,18 @@ export class AdminBillingController {
     method: "POST",
     path: `${this.url}/cash`,
     group: this.group,
-    use: [$secure({ permissions: ["billing:write"] })],
+    use: [$secure({ permissions: ["payments:write"] })],
     description: "Record a cash payment",
     schema: {
       body: recordCashSchema,
       response: intentResourceSchema,
     },
     handler: ({ body }) =>
-      this.billing.recordCashPayment(body.amount, body.currency, body.metadata),
+      this.payments.recordCashPayment(
+        body.amount,
+        body.currency,
+        body.metadata,
+      ),
   });
 
   /**
@@ -135,14 +140,14 @@ export class AdminBillingController {
    */
   public readonly webhook = $action({
     method: "POST",
-    path: "/billing/webhook",
+    path: "/payments/webhook",
     group: this.group,
     description: "PSP webhook endpoint",
     schema: {
       response: okSchema,
     },
     handler: async (request) => {
-      await this.billing.handleWebhook(request.raw.web!.req);
+      await this.payments.handleWebhook(request.raw.web!.req);
       return { ok: true };
     },
   });

package/src/{billing/controllers/BillingController.ts → api/payments/controllers/PaymentController.ts}

@@ -1,6 +1,7 @@
 import { $inject, t } from "alepha";
 import { $secure } from "alepha/security";
 import { $action, okSchema } from "alepha/server";
+import { PaymentError } from "../errors/PaymentError.ts";
 import {
   checkoutResponseSchema,
   createCheckoutSchema,
@@ -9,13 +10,13 @@ import {
   addPaymentMethodSchema,
   paymentMethodResourceSchema,
 } from "../schemas/paymentMethodSchemas.ts";
-import { BillingService } from "../services/BillingService.ts";
 import { PaymentMethodService } from "../services/PaymentMethodService.ts";
+import { PaymentService } from "../services/PaymentService.ts";
 
-export class BillingController {
-  protected readonly url = "/billing";
-  protected readonly group = "billing";
-  protected readonly billing = $inject(BillingService);
+export class PaymentController {
+  protected readonly url = "/payments";
+  protected readonly group = "payments";
+  protected readonly payments = $inject(PaymentService);
   protected readonly paymentMethods = $inject(PaymentMethodService);
 
   /**
@@ -45,12 +46,18 @@ export class BillingController {
       body: addPaymentMethodSchema,
       response: paymentMethodResourceSchema,
     },
-    handler: ({ body, user }) =>
-      this.paymentMethods.addPaymentMethod(
+    handler: ({ body, user }) => {
+      if (!user.organization) {
+        throw new PaymentError(
+          "Organization is required to add a payment method",
+        );
+      }
+      return this.paymentMethods.addPaymentMethod(
         user.id,
-        user.organization!,
+        user.organization,
         body.token,
-      ),
+      );
+    },
   });
 
   /**
@@ -102,7 +109,12 @@ export class BillingController {
       body: createCheckoutSchema,
       response: checkoutResponseSchema,
     },
-    handler: ({ body }) =>
-      this.billing.createSession(body.intentId, body.returnUrl, body.authorize),
+    handler: ({ body, user }) =>
+      this.payments.createSession(
+        body.intentId,
+        body.returnUrl,
+        body.authorize,
+        user.id,
+      ),
   });
 }

package/src/{billing → api/payments}/entities/paymentIntents.ts

@@ -16,6 +16,7 @@ export const paymentIntents = $entity({
       "processing",
       "authorized",
       "captured",
+      "partially_refunded",
       "voided",
       "failed",
       "cancelled",

package/src/{billing/errors/BillingError.ts → api/payments/errors/PaymentError.ts}

@@ -1,5 +1,5 @@
 import { AlephaError } from "alepha";
 
-export class BillingError extends AlephaError {
+export class PaymentError extends AlephaError {
   public readonly status = 400;
 }