alepha 0.19.0 → 0.19.2

package/src/api/verifications/{jobs → __tests__}/VerificationJobs.spec.ts

@@ -23,6 +23,8 @@ describe("VerificationJobs", () => {
     const time = alepha.inject(DateTimeProvider);
     const jobs = alepha.inject(VerificationJobs);
 
+    await db.verifications.deleteMany({ target: { eq: "hello@mail.com" } });
+
     const entry = {
       type: "link",
       target: "hello@mail.com",
@@ -36,12 +38,12 @@ describe("VerificationJobs", () => {
 
     await db.verifications.create({
       ...entry,
-      createdAt: time.now().subtract(1, "days").toISOString(),
+      createdAt: time.now().subtract(2, "days").toISOString(),
     });
 
     await db.verifications.create({
       ...entry,
-      createdAt: time.now().subtract(2, "days").toISOString(),
+      createdAt: time.now().subtract(3, "days").toISOString(),
     });
 
     expect(await db.verifications.count()).toBe(3);

package/src/api/verifications/parameters/VerificationParameters.ts

@@ -1,4 +1,4 @@
-import { $atom, $use, type Static } from "alepha";
+import { $atom, $state, type Static } from "alepha";
 import {
   type VerificationSettings,
   verificationSettingsSchema,
@@ -41,7 +41,7 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 export class VerificationParameters {
-  protected readonly options = $use(verificationOptions);
+  protected readonly options = $state(verificationOptions);
 
   public get<K extends keyof VerificationSettings>(
     key: K,

package/src/billing/__tests__/BillingService.spec.ts

@@ -0,0 +1,136 @@
+import { Alepha } from "alepha";
+import { AlephaOrmPostgres } from "alepha/orm/postgres";
+import { describe, it } from "vitest";
+import { AlephaBilling } from "../index.ts";
+import { BillingService } from "../services/BillingService.ts";
+
+describe("BillingService", () => {
+  it("should create an intent in 'created' status", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const billing = alepha.inject(BillingService);
+    await alepha.start();
+
+    const intent = await billing.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 alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const billing = alepha.inject(BillingService);
+    await alepha.start();
+
+    const intent = await billing.createIntent(1500, "eur");
+    const session = await billing.createSession(
+      intent.id,
+      "https://example.com/return",
+    );
+
+    expect(session.url).toContain("/billing/mock-checkout/");
+    expect(session.intentId).toBe(intent.id);
+  });
+
+  it("should capture an authorized intent", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const billing = alepha.inject(BillingService);
+    await alepha.start();
+
+    const intent = await billing.createIntent(1500, "eur");
+    await billing.createSession(intent.id, "https://example.com", true);
+    await billing.handleWebhookEvent(intent.id, "authorized");
+
+    const captured = await billing.capture(intent.id);
+    expect(captured.status).toBe("captured");
+  });
+
+  it("should void an authorized intent", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const billing = alepha.inject(BillingService);
+    await alepha.start();
+
+    const intent = await billing.createIntent(1500, "eur");
+    await billing.createSession(intent.id, "https://example.com", true);
+    await billing.handleWebhookEvent(intent.id, "authorized");
+
+    const voided = await billing.void(intent.id);
+    expect(voided.status).toBe("voided");
+  });
+
+  it("should refund a captured intent", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const billing = alepha.inject(BillingService);
+    await alepha.start();
+
+    const intent = await billing.createIntent(1500, "eur");
+    await billing.createSession(intent.id, "https://example.com");
+    await billing.handleWebhookEvent(intent.id, "captured");
+
+    const refund = await billing.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 alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const billing = alepha.inject(BillingService);
+    await alepha.start();
+
+    const intent = await billing.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 alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const billing = alepha.inject(BillingService);
+    await alepha.start();
+
+    const intent = await billing.createIntent(1500, "eur");
+    const cancelled = await billing.cancel(intent.id);
+    expect(cancelled.status).toBe("cancelled");
+  });
+
+  it("should reject capture from wrong status", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const billing = alepha.inject(BillingService);
+    await alepha.start();
+
+    const intent = await billing.createIntent(1500, "eur");
+    await expect(billing.capture(intent.id)).rejects.toThrowError();
+  });
+
+  it("should reject refund from wrong status", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const billing = alepha.inject(BillingService);
+    await alepha.start();
+
+    const intent = await billing.createIntent(1500, "eur");
+    await expect(billing.refund(intent.id, 500)).rejects.toThrowError();
+  });
+
+  it("should reject void from wrong status", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const billing = alepha.inject(BillingService);
+    await alepha.start();
+
+    const intent = await billing.createIntent(1500, "eur");
+    await expect(billing.void(intent.id)).rejects.toThrowError();
+  });
+
+  it("should reject cancel from wrong status", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const billing = alepha.inject(BillingService);
+    await alepha.start();
+
+    const intent = await billing.createIntent(1500, "eur");
+    await billing.createSession(intent.id, "https://example.com");
+    await expect(billing.cancel(intent.id)).rejects.toThrowError();
+  });
+});

package/src/billing/__tests__/PaymentMethodService.spec.ts

@@ -0,0 +1,78 @@
+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 { PaymentMethodService } from "../services/PaymentMethodService.ts";
+
+describe("PaymentMethodService", () => {
+  const userId = randomUUID();
+  const userId2 = randomUUID();
+  const orgId = randomUUID();
+  it("should add a payment method", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const service = alepha.inject(PaymentMethodService);
+    await alepha.start();
+
+    const method = await service.addPaymentMethod(userId, orgId, "tok_visa");
+    expect(method.type).toBe("card");
+    expect(method.last4).toBe("4242");
+    expect(method.isDefault).toBe(true);
+  });
+
+  it("should list payment methods for a user", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const service = alepha.inject(PaymentMethodService);
+    await alepha.start();
+
+    await service.addPaymentMethod(userId, orgId, "tok_visa");
+    await service.addPaymentMethod(userId, orgId, "tok_mastercard");
+
+    const methods = await service.listPaymentMethods(userId);
+    expect(methods).toHaveLength(2);
+  });
+
+  it("should remove a payment method", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const service = alepha.inject(PaymentMethodService);
+    await alepha.start();
+
+    const method = await service.addPaymentMethod(userId, orgId, "tok_visa");
+    await service.removePaymentMethod(method.id, userId);
+
+    const methods = await service.listPaymentMethods(userId);
+    expect(methods).toHaveLength(0);
+  });
+
+  it("should set a default payment method", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const service = alepha.inject(PaymentMethodService);
+    await alepha.start();
+
+    const method1 = await service.addPaymentMethod(userId, orgId, "tok_visa");
+    const method2 = await service.addPaymentMethod(
+      userId,
+      orgId,
+      "tok_mastercard",
+    );
+
+    await service.setDefault(method1.id, userId);
+
+    const methods = await service.listPaymentMethods(userId);
+    const defaultMethod = methods.find((m) => m.isDefault);
+    expect(defaultMethod?.id).toBe(method1.id);
+  });
+
+  it("should reject removing another user's payment method", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres).with(AlephaBilling);
+    const service = alepha.inject(PaymentMethodService);
+    await alepha.start();
+
+    const method = await service.addPaymentMethod(userId, orgId, "tok_visa");
+    await expect(
+      service.removePaymentMethod(method.id, userId2),
+    ).rejects.toThrowError();
+  });
+});

package/src/billing/controllers/AdminBillingController.ts

@@ -0,0 +1,149 @@
+import { $inject, t } from "alepha";
+import { $secure } from "alepha/security";
+import { $action, okSchema } from "alepha/server";
+import {
+  captureIntentSchema,
+  intentQuerySchema,
+  intentResourceSchema,
+  recordCashSchema,
+  refundIntentSchema,
+} from "../schemas/intentSchemas.ts";
+import { refundResourceSchema } from "../schemas/refundSchemas.ts";
+import { BillingService } from "../services/BillingService.ts";
+
+export class AdminBillingController {
+  protected readonly url = "/admin/billing";
+  protected readonly group = "admin:billing";
+  protected readonly billing = $inject(BillingService);
+
+  /**
+   * List payment intents with pagination and filtering.
+   */
+  public readonly listIntents = $action({
+    path: `${this.url}/intents`,
+    group: this.group,
+    use: [$secure({ permissions: ["billing:read"] })],
+    description: "List payment intents",
+    schema: {
+      query: intentQuerySchema,
+      response: t.page(intentResourceSchema),
+    },
+    handler: ({ query }) => this.billing.findIntents(query),
+  });
+
+  /**
+   * Get a payment intent by ID.
+   */
+  public readonly getIntent = $action({
+    path: `${this.url}/intents/:id`,
+    group: this.group,
+    use: [$secure({ permissions: ["billing:read"] })],
+    description: "Get payment intent details",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: intentResourceSchema,
+    },
+    handler: ({ params }) => this.billing.getIntent(params.id),
+  });
+
+  /**
+   * Capture an authorized intent.
+   */
+  public readonly captureIntent = $action({
+    method: "POST",
+    path: `${this.url}/intents/:id/capture`,
+    group: this.group,
+    use: [$secure({ permissions: ["billing: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),
+  });
+
+  /**
+   * Void an authorized intent.
+   */
+  public readonly voidIntent = $action({
+    method: "POST",
+    path: `${this.url}/intents/:id/void`,
+    group: this.group,
+    use: [$secure({ permissions: ["billing:write"] })],
+    description: "Void an authorized payment intent",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: intentResourceSchema,
+    },
+    handler: ({ params }) => this.billing.void(params.id),
+  });
+
+  /**
+   * Refund a captured intent.
+   */
+  public readonly refundIntent = $action({
+    method: "POST",
+    path: `${this.url}/intents/:id/refund`,
+    group: this.group,
+    use: [$secure({ permissions: ["billing:write"] })],
+    description: "Issue partial or full refund",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      body: refundIntentSchema,
+      response: refundResourceSchema,
+    },
+    handler: ({ params, body }) =>
+      this.billing.refund(params.id, body.amount, body.reason),
+  });
+
+  /**
+   * Cancel a created intent.
+   */
+  public readonly cancelIntent = $action({
+    method: "POST",
+    path: `${this.url}/intents/:id/cancel`,
+    group: this.group,
+    use: [$secure({ permissions: ["billing:write"] })],
+    description: "Cancel a created payment intent",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: intentResourceSchema,
+    },
+    handler: ({ params }) => this.billing.cancel(params.id),
+  });
+
+  /**
+   * Record a cash payment.
+   */
+  public readonly recordCash = $action({
+    method: "POST",
+    path: `${this.url}/cash`,
+    group: this.group,
+    use: [$secure({ permissions: ["billing:write"] })],
+    description: "Record a cash payment",
+    schema: {
+      body: recordCashSchema,
+      response: intentResourceSchema,
+    },
+    handler: ({ body }) =>
+      this.billing.recordCashPayment(body.amount, body.currency, body.metadata),
+  });
+
+  /**
+   * PSP webhook endpoint (not under /admin, no auth — verified by provider).
+   */
+  public readonly webhook = $action({
+    method: "POST",
+    path: "/billing/webhook",
+    group: this.group,
+    description: "PSP webhook endpoint",
+    schema: {
+      response: okSchema,
+    },
+    handler: async (request) => {
+      await this.billing.handleWebhook(request.raw.web!.req);
+      return { ok: true };
+    },
+  });
+}

package/src/billing/controllers/BillingController.ts

@@ -0,0 +1,108 @@
+import { $inject, t } from "alepha";
+import { $secure } from "alepha/security";
+import { $action, okSchema } from "alepha/server";
+import {
+  checkoutResponseSchema,
+  createCheckoutSchema,
+} from "../schemas/intentSchemas.ts";
+import {
+  addPaymentMethodSchema,
+  paymentMethodResourceSchema,
+} from "../schemas/paymentMethodSchemas.ts";
+import { BillingService } from "../services/BillingService.ts";
+import { PaymentMethodService } from "../services/PaymentMethodService.ts";
+
+export class BillingController {
+  protected readonly url = "/billing";
+  protected readonly group = "billing";
+  protected readonly billing = $inject(BillingService);
+  protected readonly paymentMethods = $inject(PaymentMethodService);
+
+  /**
+   * List the current user's saved payment methods.
+   */
+  public readonly listPaymentMethods = $action({
+    path: `${this.url}/payment-methods`,
+    group: this.group,
+    use: [$secure()],
+    description: "List current user's saved payment methods",
+    schema: {
+      response: t.array(paymentMethodResourceSchema),
+    },
+    handler: ({ user }) => this.paymentMethods.listPaymentMethods(user.id),
+  });
+
+  /**
+   * Add a new payment method.
+   */
+  public readonly addPaymentMethod = $action({
+    method: "POST",
+    path: `${this.url}/payment-methods`,
+    group: this.group,
+    use: [$secure()],
+    description: "Tokenize and store a new payment method",
+    schema: {
+      body: addPaymentMethodSchema,
+      response: paymentMethodResourceSchema,
+    },
+    handler: ({ body, user }) =>
+      this.paymentMethods.addPaymentMethod(
+        user.id,
+        user.organization!,
+        body.token,
+      ),
+  });
+
+  /**
+   * Remove a payment method.
+   */
+  public readonly removePaymentMethod = $action({
+    method: "DELETE",
+    path: `${this.url}/payment-methods/:id`,
+    group: this.group,
+    use: [$secure()],
+    description: "Remove own payment method",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: okSchema,
+    },
+    handler: async ({ params, user }) => {
+      await this.paymentMethods.removePaymentMethod(params.id, user.id);
+      return { ok: true, id: params.id };
+    },
+  });
+
+  /**
+   * Set a payment method as default.
+   */
+  public readonly setDefaultPaymentMethod = $action({
+    method: "PATCH",
+    path: `${this.url}/payment-methods/:id/default`,
+    group: this.group,
+    use: [$secure()],
+    description: "Set as default payment method",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: paymentMethodResourceSchema,
+    },
+    handler: ({ params, user }) =>
+      this.paymentMethods.setDefault(params.id, user.id),
+  });
+
+  /**
+   * Create a checkout session.
+   */
+  public readonly createCheckout = $action({
+    method: "POST",
+    path: `${this.url}/checkout`,
+    group: this.group,
+    use: [$secure()],
+    description: "Create checkout session and return URL",
+    schema: {
+      body: createCheckoutSchema,
+      response: checkoutResponseSchema,
+    },
+    handler: ({ body }) =>
+      this.billing.createSession(body.intentId, body.returnUrl, body.authorize),
+  });
+}

package/src/billing/entities/paymentIntents.ts

@@ -0,0 +1,34 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+
+export const paymentIntents = $entity({
+  name: "payment_intents",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    version: db.version(),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+    organizationId: db.organization(),
+    amount: t.integer(),
+    currency: t.text({ size: "short" }),
+    status: t.enum([
+      "created",
+      "processing",
+      "authorized",
+      "captured",
+      "voided",
+      "failed",
+      "cancelled",
+      "refunded",
+      "expired",
+    ]),
+    providerRef: t.optional(t.text()),
+    providerRaw: t.optional(t.json()),
+    metadata: t.optional(t.json()),
+    paymentMethodId: t.optional(t.uuid()),
+    userId: t.optional(t.uuid()),
+  }),
+  indexes: ["status", "organizationId", "userId", "createdAt"],
+});
+
+export type PaymentIntentEntity = Static<typeof paymentIntents.schema>;

package/src/billing/entities/paymentMethods.ts

@@ -0,0 +1,24 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+
+export const paymentMethods = $entity({
+  name: "payment_methods",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    version: db.version(),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+    organizationId: db.organization(),
+    userId: t.uuid(),
+    type: t.text({ size: "short" }),
+    brand: t.optional(t.text({ size: "short" })),
+    last4: t.optional(t.text({ size: "short" })),
+    expMonth: t.optional(t.integer()),
+    expYear: t.optional(t.integer()),
+    isDefault: t.boolean(),
+    providerRef: t.text(),
+  }),
+  indexes: ["userId", "organizationId"],
+});
+
+export type PaymentMethodEntity = Static<typeof paymentMethods.schema>;

package/src/billing/entities/refunds.ts

@@ -0,0 +1,22 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+
+export const refunds = $entity({
+  name: "refunds",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    version: db.version(),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+    organizationId: db.organization(),
+    intentId: t.uuid(),
+    amount: t.integer(),
+    currency: t.text({ size: "short" }),
+    status: t.enum(["pending", "processing", "completed", "failed"]),
+    reason: t.optional(t.text()),
+    providerRef: t.optional(t.text()),
+  }),
+  indexes: ["intentId", "organizationId", "status"],
+});
+
+export type RefundEntity = Static<typeof refunds.schema>;

package/src/billing/errors/BillingError.ts

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

package/src/billing/index.ts

@@ -0,0 +1,76 @@
+import { $module } from "alepha";
+import { AdminBillingController } from "./controllers/AdminBillingController.ts";
+import { BillingController } from "./controllers/BillingController.ts";
+import { BillingProvider } from "./providers/BillingProvider.ts";
+import { MemoryBillingProvider } from "./providers/MemoryBillingProvider.ts";
+import { BillingService } from "./services/BillingService.ts";
+import { PaymentMethodService } from "./services/PaymentMethodService.ts";
+
+export * from "./controllers/AdminBillingController.ts";
+export * from "./controllers/BillingController.ts";
+export * from "./entities/paymentIntents.ts";
+export * from "./entities/paymentMethods.ts";
+export * from "./entities/refunds.ts";
+export * from "./errors/BillingError.ts";
+export * from "./providers/BillingProvider.ts";
+export * from "./providers/MemoryBillingProvider.ts";
+export * from "./schemas/intentSchemas.ts";
+export * from "./schemas/paymentMethodSchemas.ts";
+export * from "./schemas/refundSchemas.ts";
+export * from "./services/BillingService.ts";
+export * from "./services/PaymentMethodService.ts";
+
+declare module "alepha" {
+  interface Hooks {
+    "billing:authorized": {
+      intentId: string;
+      amount: number;
+      currency: string;
+      metadata?: unknown;
+    };
+    "billing:captured": {
+      intentId: string;
+      amount: number;
+      currency: string;
+      metadata?: unknown;
+    };
+    "billing:failed": {
+      intentId: string;
+      amount: number;
+      currency: string;
+      metadata?: unknown;
+    };
+    "billing:voided": {
+      intentId: string;
+      amount: number;
+      currency: string;
+      metadata?: unknown;
+    };
+    "billing:refunded": {
+      intentId: string;
+      refundId: string;
+      amount: number;
+      currency: string;
+      metadata?: unknown;
+    };
+  }
+}
+
+export const AlephaBilling = $module({
+  name: "alepha.billing",
+  services: [
+    AdminBillingController,
+    BillingController,
+    BillingProvider,
+    MemoryBillingProvider,
+    BillingService,
+    PaymentMethodService,
+  ],
+  register: (alepha) => {
+    alepha.with({
+      optional: true,
+      provide: BillingProvider,
+      use: MemoryBillingProvider,
+    });
+  },
+});