@gravito/satellite-payment 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @gravito/satellite-payment
 
+## 0.1.5
+
+### Patch Changes
+
+- Updated dependencies
+  - @gravito/core@1.6.1
+  - @gravito/enterprise@1.0.4
+  - @gravito/stasis@3.1.1
+
 ## 0.1.4
 
 ### Patch Changes

package/dist/index.js

@@ -63,12 +63,17 @@ var ProcessPayment = class extends UseCase {
     this.manager = manager;
   }
   async execute(input) {
-    const transaction = Transaction.create(crypto.randomUUID(), {
+    const id = crypto.randomUUID();
+    const transaction = Transaction.create(id, {
       orderId: input.orderId,
       amount: input.amount,
       currency: input.currency,
       gateway: input.gateway || "default"
     });
+    if (input.metadata) {
+      ;
+      transaction.props.metadata = { ...input.metadata };
+    }
     const gateway = this.manager.driver(input.gateway);
     const intent = await gateway.createIntent(transaction);
     transaction.authorize(intent.gatewayTransactionId);
@@ -108,7 +113,9 @@ var StripeGateway = class {
       currency: rawProps.currency.toLowerCase(),
       metadata: {
         orderId: transaction.orderId,
-        transactionId: transaction.id
+        transactionId: transaction.id,
+        // 包含自定義 metadata（如 lockId）
+        ...rawProps.metadata
       },
       automatic_payment_methods: {
         enabled: true

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@gravito/satellite-payment",
-  "version": "0.1.4",
+  "sideEffects": false,
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --external @gravito/atlas --external @gravito/enterprise --external @gravito/stasis --external @gravito/core --external stripe",
+    "build": "tsup src/index.ts --format esm --clean --external @gravito/atlas --external @gravito/enterprise --external @gravito/stasis --external @gravito/core --external stripe",
+    "build:dts": "tsup src/index.ts --format esm --dts --clean --external @gravito/atlas --external @gravito/enterprise --external @gravito/stasis --external @gravito/core --external stripe",
     "test": "bun test",
-    "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck"
+    "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
+    "test:unit": "bun test",
+    "test:integration": "bun test"
   },
   "dependencies": {
     "@gravito/atlas": "workspace:*",

package/package.json.bak

@@ -0,0 +1,34 @@
+{
+  "name": "@gravito/satellite-payment",
+  "version": "0.1.4",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external @gravito/atlas --external @gravito/enterprise --external @gravito/stasis --external @gravito/core --external stripe",
+    "test": "bun test",
+    "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
+    "test:unit": "bun test",
+    "test:integration": "bun test"
+  },
+  "dependencies": {
+    "@gravito/atlas": "workspace:*",
+    "@gravito/enterprise": "workspace:*",
+    "@gravito/stasis": "workspace:*",
+    "@gravito/core": "workspace:*",
+    "stripe": "^20.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gravito-framework/gravito.git",
+    "directory": "satellites/payment"
+  }
+}

package/src/Application/UseCases/ProcessPayment.ts

@@ -8,6 +8,7 @@ export interface ProcessPaymentInput {
   amount: number
   currency: string
   gateway?: string // 現在可以動態指定
+  metadata?: Record<string, string> // 自定義 metadata（如 lockId）
 }
 
 export class ProcessPayment extends UseCase<ProcessPaymentInput, PaymentIntent> {
@@ -16,13 +17,19 @@ export class ProcessPayment extends UseCase<ProcessPaymentInput, PaymentIntent>
   }
 
   async execute(input: ProcessPaymentInput): Promise<PaymentIntent> {
-    const transaction = Transaction.create(crypto.randomUUID(), {
+    const id = crypto.randomUUID()
+    const transaction = Transaction.create(id, {
       orderId: input.orderId,
       amount: input.amount,
       currency: input.currency,
       gateway: input.gateway || 'default',
     })
 
+    // 設置自定義 metadata（如果提供）
+    if (input.metadata) {
+      ;(transaction as any).props.metadata = { ...input.metadata }
+    }
+
     // 從 Manager 取得指定的金流驅動器
     const gateway = this.manager.driver(input.gateway)
     const intent = await gateway.createIntent(transaction)

package/src/Infrastructure/Gateways/StripeGateway.ts

@@ -7,7 +7,7 @@ export class StripeGateway implements IPaymentGateway {
 
   constructor(apiKey: string) {
     this.stripe = new Stripe(apiKey, {
-      apiVersion: '2025-01-27' as any,
+      apiVersion: '2025-01-27' as never,
     })
   }
 
@@ -16,8 +16,10 @@ export class StripeGateway implements IPaymentGateway {
   }
 
   async createIntent(transaction: Transaction): Promise<PaymentIntent> {
-    // 透過 any 訪問私有屬性以解決跨包訪問問題
-    const rawProps = (transaction as any).props
+    // 透過類型斷言訪問私有屬性以解決跨包訪問問題
+    const rawProps = (
+      transaction as unknown as { props: { currency: string; metadata?: Record<string, unknown> } }
+    ).props
 
     const intent = await this.stripe.paymentIntents.create({
       amount: Math.round(transaction.amount * 100),
@@ -25,6 +27,8 @@ export class StripeGateway implements IPaymentGateway {
       metadata: {
         orderId: transaction.orderId,
         transactionId: transaction.id,
+        // 包含自定義 metadata（如 lockId）
+        ...rawProps.metadata,
       },
       automatic_payment_methods: {
         enabled: true,

package/src/manifest.json

@@ -3,13 +3,7 @@
   "id": "payment",
   "version": "0.1.0",
   "description": "A Gravito Satellite",
-  "capabilities": [
-    "create-payment"
-  ],
-  "requirements": [
-    "cache"
-  ],
-  "hooks": [
-    "payment:created"
-  ]
-}
+  "capabilities": ["create-payment"],
+  "requirements": ["cache"],
+  "hooks": ["payment:created"]
+}

package/tests/domain-entities.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from 'bun:test'
+import { Transaction, TransactionStatus } from '../src/Domain/Entities/Transaction'
+
+describe('Payment Domain - Transaction Entity', () => {
+  describe('Transaction Creation & Initial State', () => {
+    it('應該建立初始狀態為 PENDING 的交易', () => {
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+      })
+
+      expect(tx.id).toBe('tx-1')
+      expect(tx.orderId).toBe('ord-123')
+      expect(tx.amount).toBe(1000)
+      expect(tx.status).toBe(TransactionStatus.PENDING)
+      expect(tx.gateway).toBe('stripe')
+    })
+  })
+
+  describe('Transaction Status Transitions', () => {
+    it('PENDING → AUTHORIZED: authorize() 應轉移狀態並設置 gatewayId', () => {
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+      })
+
+      tx.authorize('stripe_charge_xyz')
+      expect(tx.status).toBe(TransactionStatus.AUTHORIZED)
+    })
+
+    it('AUTHORIZED → CAPTURED: capture() 應轉移狀態', () => {
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+      })
+
+      tx.authorize('stripe_charge_xyz')
+      tx.capture()
+      expect(tx.status).toBe(TransactionStatus.CAPTURED)
+    })
+
+    it('CAPTURED → REFUNDED: refund() 應轉移狀態', () => {
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+      })
+
+      tx.authorize('stripe_charge_xyz')
+      tx.capture()
+      tx.refund()
+      expect(tx.status).toBe(TransactionStatus.REFUNDED)
+    })
+
+    it('非 PENDING 時，authorize() 應拋出錯誤', () => {
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+      })
+
+      tx.authorize('stripe_charge_xyz')
+
+      expect(() => tx.authorize('another_id')).toThrow(
+        'Only pending transactions can be authorized'
+      )
+    })
+
+    it('非 AUTHORIZED 時，capture() 應拋出錯誤', () => {
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+      })
+
+      expect(() => tx.capture()).toThrow('Only authorized transactions can be captured')
+    })
+
+    it('非 CAPTURED 時，refund() 應拋出錯誤', () => {
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+      })
+
+      tx.authorize('stripe_charge_xyz')
+
+      expect(() => tx.refund()).toThrow('Only captured transactions can be refunded')
+    })
+
+    it('fail() 應將狀態設為 FAILED 並儲存失敗原因', () => {
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+      })
+
+      tx.fail('Card declined')
+      expect(tx.status).toBe(TransactionStatus.FAILED)
+    })
+  })
+
+  describe('Multiple Transaction Types', () => {
+    it('應該支援不同的支付閘道', () => {
+      const stripeTx = Transaction.create('tx-1', {
+        orderId: 'ord-1',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+      })
+
+      const paypalTx = Transaction.create('tx-2', {
+        orderId: 'ord-2',
+        amount: 2000,
+        currency: 'TWD',
+        gateway: 'paypal',
+      })
+
+      expect(stripeTx.gateway).toBe('stripe')
+      expect(paypalTx.gateway).toBe('paypal')
+    })
+  })
+})

package/tests/use-cases.test.ts

@@ -0,0 +1,381 @@
+import { describe, expect, it } from 'bun:test'
+import { ProcessPayment } from '../src/Application/UseCases/ProcessPayment'
+import { RefundPayment } from '../src/Application/UseCases/RefundPayment'
+import type { IPaymentGateway, PaymentIntent } from '../src/Domain/Contracts/IPaymentGateway'
+import { Transaction, TransactionStatus } from '../src/Domain/Entities/Transaction'
+
+/**
+ * Mock PaymentGateway
+ */
+class MockPaymentGateway implements IPaymentGateway {
+  private intents: Map<string, PaymentIntent> = new Map()
+
+  getName(): string {
+    return 'mock'
+  }
+
+  async createIntent(transaction: Transaction): Promise<PaymentIntent> {
+    const intent: PaymentIntent = {
+      gatewayTransactionId: `mock_${transaction.id}`,
+      clientSecret: `secret_${transaction.id}`,
+      status: 'requires_action',
+    }
+    this.intents.set(intent.gatewayTransactionId, intent)
+    return intent
+  }
+
+  async capture(gatewayTransactionId: string): Promise<boolean> {
+    const intent = this.intents.get(gatewayTransactionId)
+    if (!intent) {
+      return false
+    }
+    intent.status = 'succeeded'
+    return true
+  }
+
+  async refund(gatewayTransactionId: string, amount?: number): Promise<boolean> {
+    const intent = this.intents.get(gatewayTransactionId)
+    if (!intent) {
+      return false
+    }
+    intent.status = 'refunded'
+    return true
+  }
+}
+
+/**
+ * Mock PaymentManager
+ */
+class MockPaymentManager {
+  private gateways: Map<string, IPaymentGateway> = new Map()
+
+  constructor() {
+    this.gateways.set('mock', new MockPaymentGateway())
+    this.gateways.set('stripe', new MockPaymentGateway())
+  }
+
+  driver(name?: string): IPaymentGateway {
+    const driverName = name || 'stripe'
+    const gateway = this.gateways.get(driverName)
+    if (!gateway) {
+      throw new Error(`Payment driver [${driverName}] is not registered`)
+    }
+    return gateway
+  }
+
+  getGateway(name: string): MockPaymentGateway {
+    return this.gateways.get(name) as MockPaymentGateway
+  }
+}
+
+describe('Payment UseCases', () => {
+  describe('ProcessPayment', () => {
+    it('應該能成功建立支付意向', async () => {
+      const manager = new MockPaymentManager()
+      const useCase = new ProcessPayment(manager as any)
+
+      const result = await useCase.execute({
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+      })
+
+      expect(result.gatewayTransactionId).toBeDefined()
+      expect(result.clientSecret).toBeDefined()
+      expect(result.status).toBe('requires_action')
+    })
+
+    it('應該能設置自定義 metadata', async () => {
+      const manager = new MockPaymentManager()
+      const useCase = new ProcessPayment(manager as any)
+
+      const result = await useCase.execute({
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+        metadata: {
+          lockId: 'lock-xyz',
+          source: 'web',
+        },
+      })
+
+      expect(result.gatewayTransactionId).toBeDefined()
+    })
+
+    it('應該使用預設驅動器當未指定時', async () => {
+      const manager = new MockPaymentManager()
+      const useCase = new ProcessPayment(manager as any)
+
+      const result = await useCase.execute({
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+      })
+
+      expect(result.gatewayTransactionId).toBeDefined()
+    })
+
+    it('應該在不同幣別間工作', async () => {
+      const manager = new MockPaymentManager()
+      const useCase = new ProcessPayment(manager as any)
+
+      const twdResult = await useCase.execute({
+        orderId: 'ord-1',
+        amount: 1000,
+        currency: 'TWD',
+      })
+
+      const usdResult = await useCase.execute({
+        orderId: 'ord-2',
+        amount: 30,
+        currency: 'USD',
+      })
+
+      expect(twdResult.gatewayTransactionId).toBeDefined()
+      expect(usdResult.gatewayTransactionId).toBeDefined()
+    })
+
+    it('應該支援多個支付閘道', async () => {
+      const manager = new MockPaymentManager()
+      const useCase = new ProcessPayment(manager as any)
+
+      const stripeResult = await useCase.execute({
+        orderId: 'ord-1',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'stripe',
+      })
+
+      const mockResult = await useCase.execute({
+        orderId: 'ord-2',
+        amount: 2000,
+        currency: 'TWD',
+        gateway: 'mock',
+      })
+
+      expect(stripeResult.gatewayTransactionId).toBeDefined()
+      expect(mockResult.gatewayTransactionId).toBeDefined()
+    })
+
+    it('當驅動器不存在時應拋出錯誤', async () => {
+      const manager = new MockPaymentManager()
+      const useCase = new ProcessPayment(manager as any)
+
+      try {
+        await useCase.execute({
+          orderId: 'ord-123',
+          amount: 1000,
+          currency: 'TWD',
+          gateway: 'nonexistent',
+        })
+        expect.unreachable('應該拋出錯誤')
+      } catch (error: any) {
+        expect(error.message).toContain('not registered')
+      }
+    })
+  })
+
+  describe('RefundPayment', () => {
+    it('應該能成功退款', async () => {
+      const gateway = new MockPaymentGateway()
+
+      // 先建立一筆交易
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'mock',
+      })
+
+      const intent = await gateway.createIntent(tx)
+
+      // 執行退款
+      const useCase = new RefundPayment(gateway)
+      const result = await useCase.execute({
+        gatewayTransactionId: intent.gatewayTransactionId,
+      })
+
+      expect(result).toBe(true)
+    })
+
+    it('應該能支援部分退款', async () => {
+      const gateway = new MockPaymentGateway()
+
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'mock',
+      })
+
+      const intent = await gateway.createIntent(tx)
+
+      const useCase = new RefundPayment(gateway)
+      const result = await useCase.execute({
+        gatewayTransactionId: intent.gatewayTransactionId,
+        amount: 500,
+      })
+
+      expect(result).toBe(true)
+    })
+
+    it('當交易不存在時應返回 false', async () => {
+      const gateway = new MockPaymentGateway()
+      const useCase = new RefundPayment(gateway)
+
+      const result = await useCase.execute({
+        gatewayTransactionId: 'nonexistent_tx',
+      })
+
+      expect(result).toBe(false)
+    })
+
+    it('應該能連續退款多筆交易', async () => {
+      const gateway = new MockPaymentGateway()
+
+      // 建立多筆交易
+      const tx1 = Transaction.create('tx-1', {
+        orderId: 'ord-1',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'mock',
+      })
+      const tx2 = Transaction.create('tx-2', {
+        orderId: 'ord-2',
+        amount: 2000,
+        currency: 'TWD',
+        gateway: 'mock',
+      })
+
+      const intent1 = await gateway.createIntent(tx1)
+      const intent2 = await gateway.createIntent(tx2)
+
+      const useCase = new RefundPayment(gateway)
+
+      const result1 = await useCase.execute({
+        gatewayTransactionId: intent1.gatewayTransactionId,
+      })
+      const result2 = await useCase.execute({
+        gatewayTransactionId: intent2.gatewayTransactionId,
+      })
+
+      expect(result1).toBe(true)
+      expect(result2).toBe(true)
+    })
+  })
+
+  describe('Transaction State Machine with UseCases', () => {
+    it('應該能從 PENDING 經過 AUTHORIZED 到 CAPTURED', async () => {
+      const gateway = new MockPaymentGateway()
+
+      // 1. 建立交易（ProcessPayment）
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'mock',
+      })
+
+      expect(tx.status).toBe(TransactionStatus.PENDING)
+
+      // 2. 建立支付意向
+      const intent = await gateway.createIntent(tx)
+      tx.authorize(intent.gatewayTransactionId)
+
+      expect(tx.status).toBe(TransactionStatus.AUTHORIZED)
+
+      // 3. 清算
+      await gateway.capture(intent.gatewayTransactionId)
+      tx.capture()
+
+      expect(tx.status).toBe(TransactionStatus.CAPTURED)
+    })
+
+    it('應該能在已清算狀態退款', async () => {
+      const gateway = new MockPaymentGateway()
+
+      // 建立並處理交易
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'mock',
+      })
+
+      const intent = await gateway.createIntent(tx)
+      tx.authorize(intent.gatewayTransactionId)
+      tx.capture()
+
+      // 執行退款
+      const useCase = new RefundPayment(gateway)
+      const result = await useCase.execute({
+        gatewayTransactionId: intent.gatewayTransactionId,
+      })
+
+      tx.refund()
+
+      expect(result).toBe(true)
+      expect(tx.status).toBe(TransactionStatus.REFUNDED)
+    })
+
+    it('應該防止無效的狀態轉移', async () => {
+      const tx = Transaction.create('tx-1', {
+        orderId: 'ord-123',
+        amount: 1000,
+        currency: 'TWD',
+        gateway: 'mock',
+      })
+
+      // 不能在 PENDING 狀態捕獲
+      expect(() => tx.capture()).toThrow('Only authorized transactions can be captured')
+
+      tx.authorize('gateway_id')
+
+      // 不能在 AUTHORIZED 狀態退款
+      expect(() => tx.refund()).toThrow('Only captured transactions can be refunded')
+    })
+  })
+
+  describe('Edge Cases', () => {
+    it('應該能處理大金額交易', async () => {
+      const manager = new MockPaymentManager()
+      const useCase = new ProcessPayment(manager as any)
+
+      const result = await useCase.execute({
+        orderId: 'ord-999999',
+        amount: 999999999,
+        currency: 'TWD',
+      })
+
+      expect(result.gatewayTransactionId).toBeDefined()
+    })
+
+    it('應該能處理極小金額交易', async () => {
+      const manager = new MockPaymentManager()
+      const useCase = new ProcessPayment(manager as any)
+
+      const result = await useCase.execute({
+        orderId: 'ord-1',
+        amount: 1,
+        currency: 'TWD',
+      })
+
+      expect(result.gatewayTransactionId).toBeDefined()
+    })
+
+    it('應該能處理 0 金額（測試場景）', async () => {
+      const manager = new MockPaymentManager()
+      const useCase = new ProcessPayment(manager as any)
+
+      const result = await useCase.execute({
+        orderId: 'ord-free',
+        amount: 0,
+        currency: 'TWD',
+      })
+
+      expect(result.gatewayTransactionId).toBeDefined()
+    })
+  })
+})

package/tsconfig.json

@@ -1,26 +1,14 @@
 {
-    "extends": "../../tsconfig.json",
-    "compilerOptions": {
-        "outDir": "./dist",
-        "baseUrl": ".",
-        "paths": {
-            "@gravito/core": [
-                "../../packages/core/src/index.ts"
-            ],
-            "@gravito/*": [
-                "../../packages/*/src/index.ts"
-            ]
-        },
-        "types": [
-            "bun-types"
-        ]
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "baseUrl": ".",
+    "paths": {
+      "@gravito/core": ["../../packages/core/src/index.ts"],
+      "@gravito/*": ["../../packages/*/src/index.ts"]
     },
-    "include": [
-        "src/**/*"
-    ],
-    "exclude": [
-        "node_modules",
-        "dist",
-        "**/*.test.ts"
-    ]
-}
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/dist/index.d.ts

@@ -1,8 +0,0 @@
-import { ServiceProvider, Container } from '@gravito/core';
-
-declare class PaymentServiceProvider extends ServiceProvider {
-    register(container: Container): void;
-    boot(): void;
-}
-
-export { PaymentServiceProvider };