alepha 0.19.1 → 0.19.3

package/src/billing/services/BillingService.ts

@@ -0,0 +1,325 @@
+import { $inject, Alepha } from "alepha";
+import { $job } from "alepha/api/jobs";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { $repository } from "alepha/orm";
+import {
+  type PaymentIntentEntity,
+  paymentIntents,
+} from "../entities/paymentIntents.ts";
+import { type RefundEntity, refunds } from "../entities/refunds.ts";
+import { BillingError } from "../errors/BillingError.ts";
+import { BillingProvider } from "../providers/BillingProvider.ts";
+
+export class BillingService {
+  protected readonly alepha = $inject(Alepha);
+  protected readonly log = $logger();
+  protected readonly dateTime = $inject(DateTimeProvider);
+  protected readonly provider = $inject(BillingProvider);
+  protected readonly intentRepo = $repository(paymentIntents);
+  protected readonly refundRepo = $repository(refunds);
+
+  /**
+   * Expires stale payment intents that have been in "processing" status
+   * for more than 30 minutes. Runs every 15 minutes.
+   */
+  protected readonly expireStaleIntents = $job({
+    cron: "*/15 * * * *",
+    handler: async () => {
+      const cutoff = this.dateTime.now().subtract(30, "minutes").toISOString();
+
+      const stale = await this.intentRepo.findMany({
+        where: { status: { eq: "processing" }, createdAt: { lt: cutoff } },
+      });
+
+      for (const intent of stale) {
+        if (intent.providerRef) {
+          try {
+            await this.provider.expireSession(intent.providerRef);
+          } catch (error) {
+            this.log.warn(
+              `Failed to expire session for intent ${intent.id}`,
+              error,
+            );
+          }
+        }
+        await this.intentRepo.updateById(intent.id, { status: "expired" });
+        this.log.info(`Expired stale intent ${intent.id}`);
+      }
+    },
+  });
+
+  /**
+   * Create a new payment intent in "created" status.
+   */
+  public async createIntent(
+    amount: number,
+    currency: string,
+    metadata?: unknown,
+    options?: { paymentMethodId?: string; userId?: string },
+  ): Promise<PaymentIntentEntity> {
+    return await this.intentRepo.create({
+      amount,
+      currency,
+      status: "created",
+      metadata: metadata as any,
+      paymentMethodId: options?.paymentMethodId,
+      userId: options?.userId,
+    });
+  }
+
+  /**
+   * Create a checkout session with the payment provider and
+   * transition the intent to "processing".
+   */
+  public async createSession(
+    intentId: string,
+    returnUrl: string,
+    authorize?: boolean,
+  ): Promise<{ url: string; intentId: string }> {
+    const intent = await this.getIntent(intentId);
+    this.assertStatus(intent, "created", "createSession");
+
+    const result = await this.provider.createSession(intent, {
+      returnUrl,
+      authorize,
+    });
+
+    await this.intentRepo.updateById(intent.id, {
+      status: "processing",
+      providerRef: result.providerRef,
+    });
+
+    return { url: result.url, intentId: intent.id };
+  }
+
+  /**
+   * Handle an incoming webhook from the payment provider.
+   */
+  public async handleWebhook(request: Request): Promise<void> {
+    const event = await this.provider.parseWebhook(request);
+    const intents = await this.intentRepo.findMany({
+      where: { providerRef: { eq: event.providerRef } },
+      limit: 1,
+    });
+
+    if (intents.length === 0) {
+      this.log.warn(`Webhook for unknown providerRef: ${event.providerRef}`);
+      return;
+    }
+
+    const intent = intents[0];
+    await this.handleWebhookEvent(intent.id, event.status, event.raw);
+  }
+
+  /**
+   * Process a webhook event by updating the intent status and emitting
+   * the corresponding billing event.
+   */
+  public async handleWebhookEvent(
+    intentId: string,
+    status: string,
+    raw?: unknown,
+  ): Promise<void> {
+    const intent = await this.getIntent(intentId);
+
+    const eventMap = {
+      authorized: "billing:authorized",
+      captured: "billing:captured",
+      failed: "billing:failed",
+    } as const;
+
+    type WebhookStatus = keyof typeof eventMap;
+    if (!(status in eventMap)) {
+      this.log.warn(`Unknown webhook status: ${status}`);
+      return;
+    }
+
+    const webhookStatus = status as WebhookStatus;
+
+    await this.intentRepo.updateById(intent.id, {
+      status: webhookStatus,
+      providerRaw: raw as any,
+    });
+
+    await this.alepha.events.emit(eventMap[webhookStatus], {
+      intentId: intent.id,
+      amount: intent.amount,
+      currency: intent.currency,
+      metadata: intent.metadata,
+    });
+  }
+
+  /**
+   * Capture a previously authorized payment. Optionally specify a different
+   * amount for partial capture.
+   */
+  public async capture(
+    intentId: string,
+    finalAmount?: number,
+  ): Promise<PaymentIntentEntity> {
+    const intent = await this.getIntent(intentId);
+    this.assertStatus(intent, "authorized", "capture");
+
+    const amount = finalAmount ?? intent.amount;
+    if (intent.providerRef) {
+      await this.provider.capturePayment(intent.providerRef, amount);
+    }
+
+    const updated = await this.intentRepo.updateById(intent.id, {
+      status: "captured",
+      amount,
+    });
+
+    await this.alepha.events.emit("billing:captured", {
+      intentId: intent.id,
+      amount,
+      currency: intent.currency,
+      metadata: intent.metadata,
+    });
+
+    return updated;
+  }
+
+  /**
+   * Void a previously authorized payment before capture.
+   */
+  public async void(intentId: string): Promise<PaymentIntentEntity> {
+    const intent = await this.getIntent(intentId);
+    this.assertStatus(intent, "authorized", "void");
+
+    if (intent.providerRef) {
+      await this.provider.voidPayment(intent.providerRef);
+    }
+
+    const updated = await this.intentRepo.updateById(intent.id, {
+      status: "voided",
+    });
+
+    await this.alepha.events.emit("billing:voided", {
+      intentId: intent.id,
+      amount: intent.amount,
+      currency: intent.currency,
+      metadata: intent.metadata,
+    });
+
+    return updated;
+  }
+
+  /**
+   * Refund a captured payment (partial or full).
+   */
+  public async refund(
+    intentId: string,
+    amount: number,
+    reason?: string,
+  ): Promise<RefundEntity> {
+    const intent = await this.getIntent(intentId);
+    this.assertStatus(intent, "captured", "refund");
+
+    let refundProviderRef: string | undefined;
+    if (intent.providerRef) {
+      const result = await this.provider.refundPayment(
+        intent.providerRef,
+        amount,
+      );
+      refundProviderRef = result.providerRef;
+    }
+
+    const refund = await this.refundRepo.create({
+      intentId: intent.id,
+      organizationId: intent.organizationId,
+      amount,
+      currency: intent.currency,
+      status: "completed",
+      reason,
+      providerRef: refundProviderRef,
+    });
+
+    await this.intentRepo.updateById(intent.id, { status: "refunded" });
+
+    await this.alepha.events.emit("billing:refunded", {
+      intentId: intent.id,
+      refundId: refund.id,
+      amount,
+      currency: intent.currency,
+      metadata: intent.metadata,
+    });
+
+    return refund;
+  }
+
+  /**
+   * Record a cash or offline payment directly as captured,
+   * bypassing the checkout flow.
+   */
+  public async recordCashPayment(
+    amount: number,
+    currency: string,
+    metadata?: unknown,
+  ): Promise<PaymentIntentEntity> {
+    const intent = await this.intentRepo.create({
+      amount,
+      currency,
+      status: "captured",
+      metadata: metadata as any,
+    });
+
+    await this.alepha.events.emit("billing:captured", {
+      intentId: intent.id,
+      amount,
+      currency,
+      metadata,
+    });
+
+    return intent;
+  }
+
+  /**
+   * Cancel a payment intent that has not yet entered processing.
+   */
+  public async cancel(intentId: string): Promise<PaymentIntentEntity> {
+    const intent = await this.getIntent(intentId);
+    this.assertStatus(intent, "created", "cancel");
+
+    return await this.intentRepo.updateById(intent.id, {
+      status: "cancelled",
+    });
+  }
+
+  /**
+   * Get a payment intent by ID. Throws NotFoundError if not found.
+   */
+  public async getIntent(intentId: string): Promise<PaymentIntentEntity> {
+    return await this.intentRepo.getById(intentId);
+  }
+
+  /**
+   * Find payment intents with optional filters and pagination.
+   */
+  public async findIntents(query: {
+    status?: string;
+    userId?: string;
+    sort?: string;
+    size?: number;
+    page?: number;
+  }) {
+    const where = this.intentRepo.createQueryWhere();
+    if (query.status)
+      where.status = { eq: query.status as PaymentIntentEntity["status"] };
+    if (query.userId) where.userId = { eq: query.userId };
+    return await this.intentRepo.paginate(query, { where }, { count: true });
+  }
+
+  protected assertStatus(
+    intent: PaymentIntentEntity,
+    expected: PaymentIntentEntity["status"],
+    operation: string,
+  ): void {
+    if (intent.status !== expected) {
+      throw new BillingError(
+        `Cannot ${operation}: intent ${intent.id} is '${intent.status}', expected '${expected}'`,
+      );
+    }
+  }
+}

package/src/billing/services/PaymentMethodService.ts

@@ -0,0 +1,82 @@
+import { $inject } from "alepha";
+import { $logger } from "alepha/logger";
+import { $repository } from "alepha/orm";
+import {
+  type PaymentMethodEntity,
+  paymentMethods,
+} from "../entities/paymentMethods.ts";
+import { BillingError } from "../errors/BillingError.ts";
+import { BillingProvider } from "../providers/BillingProvider.ts";
+
+export class PaymentMethodService {
+  protected readonly log = $logger();
+  protected readonly provider = $inject(BillingProvider);
+  protected readonly methodRepo = $repository(paymentMethods);
+
+  public async addPaymentMethod(
+    userId: string,
+    organizationId: string,
+    token: string,
+  ): Promise<PaymentMethodEntity> {
+    const result = await this.provider.createPaymentMethod(userId, token);
+
+    const existing = await this.methodRepo.findMany({
+      where: { userId: { eq: userId } },
+    });
+
+    return await this.methodRepo.create({
+      userId,
+      organizationId,
+      type: result.type,
+      brand: result.brand,
+      last4: result.last4,
+      expMonth: result.expMonth,
+      expYear: result.expYear,
+      isDefault: existing.length === 0,
+      providerRef: result.providerRef,
+    });
+  }
+
+  public async listPaymentMethods(
+    userId: string,
+  ): Promise<PaymentMethodEntity[]> {
+    return await this.methodRepo.findMany({
+      where: { userId: { eq: userId } },
+    });
+  }
+
+  public async removePaymentMethod(
+    methodId: string,
+    userId: string,
+  ): Promise<void> {
+    const method = await this.methodRepo.getById(methodId);
+    if (method.userId !== userId) {
+      throw new BillingError("Cannot remove another user's payment method");
+    }
+
+    await this.provider.deletePaymentMethod(method.providerRef);
+    await this.methodRepo.deleteById(method.id);
+  }
+
+  public async setDefault(
+    methodId: string,
+    userId: string,
+  ): Promise<PaymentMethodEntity> {
+    const method = await this.methodRepo.getById(methodId);
+    if (method.userId !== userId) {
+      throw new BillingError("Cannot modify another user's payment method");
+    }
+
+    const userMethods = await this.methodRepo.findMany({
+      where: { userId: { eq: userId } },
+    });
+
+    for (const m of userMethods) {
+      if (m.isDefault) {
+        await this.methodRepo.updateById(m.id, { isDefault: false });
+      }
+    }
+
+    return await this.methodRepo.updateById(method.id, { isDefault: true });
+  }
+}

package/src/bin/index.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import { Alepha, run } from "alepha";
 import { AlephaCli, version } from "alepha/cli";
-import { AlephaCliPlatform } from "alepha/cli/platform";
 
 const alepha = Alepha.create({
   env: {
@@ -14,6 +13,5 @@ const alepha = Alepha.create({
 });
 
 alepha.with(AlephaCli);
-alepha.with(AlephaCliPlatform);
 
 run(alepha);

package/src/bucket/providers/LocalFileStorageProvider.ts

@@ -8,7 +8,7 @@ import {
   $atom,
   $hook,
   $inject,
-  $use,
+  $state,
   Alepha,
   AlephaError,
   type FileLike,
@@ -55,7 +55,7 @@ export class LocalFileStorageProvider implements FileStorageProvider {
   protected readonly log = $logger();
   protected readonly fileDetector = $inject(FileDetector);
   protected readonly fileSystemProvider = $inject(FileSystemProvider);
-  protected readonly options = $use(localFileStorageOptions);
+  protected readonly options = $state(localFileStorageOptions);
 
   protected get storagePath(): string {
     return this.options.storagePath;

package/src/cache/core/{primitives → __tests__}/$cache.middleware.spec.ts

@@ -1,7 +1,7 @@
 import { $pipeline, Alepha } from "alepha";
 import { describe, test } from "vitest";
 import { AlephaCache } from "../index.ts";
-import { $cache } from "./$cache.ts";
+import { $cache } from "../primitives/$cache.ts";
 
 describe("$cache middleware", () => {
   test("caches handler result", async ({ expect }) => {

package/src/cache/core/{providers → __tests__}/MemoryCacheProvider.spec.ts

@@ -1,7 +1,7 @@
 import { Alepha } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { beforeEach, describe, expect, it } from "vitest";
-import { MemoryCacheProvider } from "./MemoryCacheProvider.ts";
+import { MemoryCacheProvider } from "../providers/MemoryCacheProvider.ts";
 
 describe("MemoryCacheProvider", () => {
   let alepha: Alepha;

package/src/cache/core/primitives/$cache.ts

@@ -1,7 +1,7 @@
 import {
   $atom,
   $inject,
-  $use,
+  $state,
   AlephaError,
   createPrimitive,
   type InstantiableClass,
@@ -173,7 +173,7 @@ export class CachePrimitive<
   TReturn = any,
   TParameter extends any[] = any[],
 > extends Primitive<CachePrimitiveOptions<TReturn, TParameter>> {
-  protected readonly settings = $use(cacheOptions);
+  protected readonly settings = $state(cacheOptions);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   public readonly provider = this.$provider();
 

package/src/cache/redis/providers/RedisCacheProvider.ts

@@ -1,4 +1,4 @@
-import { $atom, $inject, $use, Alepha, type Static, t } from "alepha";
+import { $atom, $inject, $state, Alepha, type Static, t } from "alepha";
 import { CacheProvider } from "alepha/cache";
 import { $logger } from "alepha/logger";
 import { RedisProvider } from "alepha/redis";
@@ -34,7 +34,7 @@ declare module "alepha" {
 export class RedisCacheProvider extends CacheProvider {
   protected readonly log = $logger();
   protected readonly redisProvider = $inject(RedisProvider);
-  protected readonly options = $use(redisCacheOptions);
+  protected readonly options = $state(redisCacheOptions);
   protected readonly alepha = $inject(Alepha);
 
   public async get(name: string, key: string): Promise<Uint8Array | undefined> {

package/src/cli/config/defineConfig.ts

@@ -7,18 +7,23 @@ import {
   type DevOptions,
   devOptions,
 } from "alepha/cli";
-import { type PlatformOptions, platformOptions } from "alepha/cli/platform";
-import type { CommandPrimitive } from "alepha/command";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export type AlephaCliConfigPlugin = (
+  config: AlephaCliConfig,
+  alepha: Alepha,
+) => void;
+
+export const cliConfigPlugins: AlephaCliConfigPlugin[] = [];
+
+// ---------------------------------------------------------------------------------------------------------------------
 
 export interface AlephaCliConfig {
-  entry?: AppEntryOptions;
   /**
-   * Add custom commands to the Alepha CLI.
-   *
-   * You can override 'deploy', 'build', 'dev', 'start' commands this way.
-   * But you can also add your own commands and run them via `alepha <command>`.
+   * Override entry paths.
    */
-  commands?: Record<string, CommandPrimitive>;
+  entry?: AppEntryOptions;
 
   /**
    * Register more services to the Alepha CLI (enhancements, commands, etc.).
@@ -41,24 +46,12 @@ export interface AlephaCliConfig {
    * Always use .env files by default, this is only for dynamic values.
    */
   env?: Record<string, unknown>;
-
-  /**
-   * Platform deployment configuration.
-   */
-  platform?: PlatformOptions;
 }
 
-export type AlephaCliConfigFn = (alepha: Alepha) => AlephaCliConfig;
-
 // ---------------------------------------------------------------------------------------------------------------------
 
-export const defineConfig = (
-  runConfig: AlephaCliConfig | AlephaCliConfigFn,
-) => {
+export const defineConfig = (config: AlephaCliConfig) => {
   return (alepha: Alepha) => {
-    const config =
-      typeof runConfig === "function" ? runConfig(alepha) : runConfig;
-
     if (config.services) {
       for (const it of config.services) {
         alepha.with(it);
@@ -83,12 +76,10 @@ export const defineConfig = (
       alepha.set(appEntryOptions, config.entry);
     }
 
-    if (config.platform) {
-      alepha.set(platformOptions, config.platform);
+    for (const plugin of cliConfigPlugins) {
+      plugin(config, alepha);
     }
 
-    return {
-      ...config.commands,
-    };
+    return {};
   };
 };

package/src/cli/core/{services → __tests__}/ProjectScaffolder.spec.ts

@@ -6,7 +6,7 @@ import {
   ShellProvider,
 } from "alepha/system";
 import { describe, expect, it } from "vitest";
-import { ProjectScaffolder } from "./ProjectScaffolder.ts";
+import { ProjectScaffolder } from "../services/ProjectScaffolder.ts";
 
 describe("ProjectScaffolder", () => {
   const createTestEnv = () => {

package/src/cli/core/{commands/gen → __tests__}/changelog.spec.ts

@@ -10,7 +10,7 @@ import {
   changelogOptions,
   GitMessageParser,
   GitProvider,
-} from "./changelog.ts";
+} from "../commands/gen/changelog.ts";
 
 // =============================================================================
 // MOCK GIT PROVIDER

package/src/cli/core/{commands → __tests__}/init.spec.ts

@@ -7,7 +7,7 @@ import {
   ShellProvider,
 } from "alepha/system";
 import { describe, expect, it } from "vitest";
-import { InitCommand } from "./init.ts";
+import { InitCommand } from "../commands/init.ts";
 
 describe("alepha init", () => {
   const createTestEnv = () => {
@@ -542,13 +542,7 @@ describe("alepha init", () => {
     });
 
     it("should check each codegen flag independently", async () => {
-      for (const flag of [
-        "--react",
-        "--ui",
-        "--auth",
-        "--admin",
-        "--tailwind",
-      ]) {
+      for (const flag of ["--react", "--ui", "--saas", "--tailwind"]) {
         const { fs, cli, cmd, json } = createTestEnv();
         await setupProject(fs, json);
         await fs.writeFile("/project/src/existing.ts", "export {}");

package/src/cli/core/atoms/devOptions.ts

@@ -10,11 +10,6 @@ export const devOptions = $atom({
   name: "alepha.cli.dev.options",
   description: "Dev configuration options",
   schema: t.object({
-    /**
-     * Disable devtools.
-     */
-    noDevtools: t.optional(t.boolean({ default: false })),
-
     /**
      * Disable Vite React plugin.
      */

package/src/cli/core/commands/build.ts

@@ -1,4 +1,4 @@
-import { $inject, $use, Alepha, AlephaError, t } from "alepha";
+import { $inject, $state, Alepha, AlephaError, t } from "alepha";
 import { $command } from "alepha/command";
 import { $logger } from "alepha/logger";
 import {
@@ -31,7 +31,7 @@ export class BuildCommand {
   protected readonly scaffolder = $inject(ProjectScaffolder);
   protected readonly boot = $inject(AppEntryProvider);
   protected readonly viteBuildProvider = $inject(ViteBuildProvider);
-  protected readonly options = $use(buildOptions);
+  protected readonly options = $state(buildOptions);
 
   /**
    * Build pipeline: tasks run sequentially in this order.