Feat(feature): Modular payment-processor plugin system (Grantfox & Stellar)

.github/workflows/build-check.yml

@@ -14,7 +14,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "22"
           cache: "npm"
 
       - name: Install dependencies
@@ -57,7 +57,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "22"
           cache: "npm"
 
       - name: Install dependencies

jest.config.js

@@ -3,8 +3,20 @@ module.exports = {
   rootDir: 'src',
   testRegex: '.*\\.spec\\.ts$',
   transform: {
+    // Some deps pulled in by @stellar/stellar-sdk (uint8array-extras, @noble/*,
+    // smol-toml, eventsource) publish untranspiled ESM (`export`/`import`) in
+    // their .js. Jest ignores node_modules by default (see
+    // transformIgnorePatterns below); down-level just those files with an
+    // isolated, no-type-check transpile so they load under CommonJS.
+    '.+/node_modules/.+\\.js$': ['ts-jest', { isolatedModules: true }],
     '^.+\\.(t|j)s$': 'ts-jest',
   },
+  transformIgnorePatterns: [
+    // Keep ignoring node_modules EXCEPT the ESM-only chain under
+    // @stellar/stellar-sdk, which must be transpiled to load in Jest.
+    '/node_modules/(?!(@stellar|@noble|@exodus|stellar-base|uint8array-extras|smol-toml|eventsource)/)',
+    '\\.pnp\\.[^\\/]+$',
+  ],
   moduleNameMapper: {
     // Resolve absolute "src/..." imports (tsconfig baseUrl) under rootDir.
     '^src/(.*)$': '<rootDir>/$1',

package.json

@@ -75,6 +75,7 @@
     "@opentelemetry/sdk-trace-base": "^2.5.0",
     "@sentry/nestjs": "^10.59.0",
     "@sentry/node": "^8.4.0",
+    "@stellar/stellar-sdk": "^17.0.0",
     "@types/bcrypt": "^6.0.0",
     "@types/multer": "^2.1.0",
     "@types/qrcode": "^1.5.6",

src/app.module.ts

@@ -53,6 +53,8 @@ import { LoggerModule } from "./logging/logger.module";
 // Modules – cache
 import { CacheModule } from "./common/cache/cache.module";
 import { BillingModule } from "./billing/billing.module";
+// Modules – payments (plugin system)
+import { PaymentsModule } from "./payments/payments.module";
 import { RateLimitingModule } from "./rate-limiting/rate-limiting.module";
 import { ReconciliationModule } from "./reconciliation/reconciliation.module";
 
@@ -268,6 +270,7 @@ import { TenantModuleState } from "./modules/registry/entities/tenant-module-sta
       }),
     }),
     BillingModule,
+    PaymentsModule,
     ReconciliationModule,
   ],
 

src/config/env.validation.ts

@@ -538,6 +538,37 @@ export class EnvironmentVariables {
   @IsString()
   REDIS_PASSWORD?: string;
 
+  // ── Payment Processors (plugin system) ─────────────────────────────
+
+  /** Default processor when no `X-Payment-Processor` header is supplied, e.g. "stellar". */
+  @IsOptional()
+  @IsString()
+  PAYMENTS_DEFAULT_PROCESSOR?: string;
+
+  /** Stellar Horizon endpoint. Default: https://horizon-testnet.stellar.org */
+  @IsOptional()
+  @IsString()
+  STELLAR_HORIZON_URL?: string;
+
+  /** Stellar network passphrase. Default: testnet passphrase. */
+  @IsOptional()
+  @IsString()
+  STELLAR_NETWORK_PASSPHRASE?: string;
+
+  /** Secret seed the server signs Stellar transactions/refunds with. */
+  @IsOptional()
+  @IsString()
+  STELLAR_SIGNING_SECRET?: string;
+
+  /** Base URL of the Grantfox REST gateway. */
+  @IsOptional()
+  @IsString()
+  GRANTFOX_API_URL?: string;
+
+  /** Bearer API key for the Grantfox gateway. */
+  @IsOptional()
+  @IsString()
+  GRANTFOX_API_KEY?: string;
   // Rate Limiting & Abuse Protection (distributed, Redis-backed)
 
   /** Redis key prefix for rate-limit entries. Default: "alian:rl:". */