@gravito/satellite-payment 0.1.1

package/.dockerignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+.git
+.env
+*.log
+.vscode
+.idea
+tests

package/.env.example

@@ -0,0 +1,19 @@
+# Application
+APP_NAME="payment"
+APP_ENV=development
+APP_KEY=
+APP_DEBUG=true
+APP_URL=http://localhost:3000
+
+# Server
+PORT=3000
+
+# Database
+DB_CONNECTION=sqlite
+DB_DATABASE=database/database.sqlite
+
+# Cache
+CACHE_DRIVER=memory
+
+# Logging
+LOG_LEVEL=debug

package/ARCHITECTURE.md

@@ -0,0 +1,14 @@
+# payment Satellite Architecture
+
+This satellite follows the Gravito Satellite Specification v1.0.
+
+## Design
+- **DDD**: Domain logic is separated from framework concerns.
+- **Dogfooding**: Uses official Gravito modules (@gravito/atlas, @gravito/stasis).
+- **Decoupled**: Inter-satellite communication happens via Contracts and Events.
+
+## Layers
+- **Domain**: Pure business rules.
+- **Application**: Orchestration of domain tasks.
+- **Infrastructure**: Implementation of persistence and external services.
+- **Interface**: HTTP and Event entry points.

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @gravito/satellite-payment
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @gravito/atlas@1.0.1
+  - @gravito/core@1.0.0
+  - @gravito/enterprise@1.0.0
+  - @gravito/stasis@1.0.0

package/Dockerfile

@@ -0,0 +1,25 @@
+FROM oven/bun:1.0 AS base
+WORKDIR /usr/src/app
+
+# Install dependencies
+FROM base AS install
+RUN mkdir -p /temp/dev
+COPY package.json bun.lockb /temp/dev/
+RUN cd /temp/dev && bun install --frozen-lockfile
+
+# Build application
+FROM base AS build
+COPY --from=install /temp/dev/node_modules node_modules
+COPY . .
+ENV NODE_ENV=production
+RUN bun run build
+
+# Final production image
+FROM base AS release
+COPY --from=build /usr/src/app/dist/bootstrap.js index.js
+COPY --from=build /usr/src/app/package.json .
+
+# Create a non-root user for security
+USER bun
+EXPOSE 3000/tcp
+ENTRYPOINT [ "bun", "run", "index.js" ]

package/WHITEPAPER.md

@@ -0,0 +1,43 @@
+# Gravito Payment Satellite - Technical Whitepaper
+
+## Overview
+The Payment Satellite is the financial clearing house of the Gravito ecosystem. It provides a standardized, asynchronous, and secure way to handle monetary transactions using the **GASS (Gravito Asynchronous Satellite Specification)**.
+
+## Core Concepts
+
+### 1. Transaction Ledger
+Unlike simple payment callbacks, the Payment satellite maintains an immutable ledger of transactions. Every payment intent, authorization, and capture is logged as a state transition in the `Transaction` entity.
+
+### 2. Dual-Phase Clearing (Authorize & Capture)
+To support high-trust commerce, the satellite supports a two-step clearing process:
+- **Authorize**: Reserve funds on the user's payment method (triggered by order creation).
+- **Capture**: Finalize the transfer (triggered by shipping or digital delivery).
+
+## Propulsion Stages
+
+### Stage 1: Standard (SQL)
+- Records all ledger entries in relational tables.
+- Ensures strict ACID compliance for financial auditing.
+
+### Stage 2: Sport (In-Memory)
+- **Intent Pre-warming**: When a user enters the checkout page, the satellite pre-computes the PaymentIntent and caches it in memory.
+- Reduces checkout latency by ~200ms.
+
+### Stage 3: Turbo (Asynchronous Webhooks)
+- Utilizes `gravito-echo` to handle high-frequency webhooks from Stripe/PayPal.
+- Processes clearing and fraud checks in background queues to keep the main thread responsive.
+
+## Event Driven Architecture
+
+### Outbound Events
+- `payment:intent:ready`: Notifies Commerce that the payment session is ready for the UI.
+- `payment:succeeded`: Notifies Commerce to mark the order as `PAID`.
+- `payment:refund:succeeded`: Notifies Commerce to mark the order as `REFUNDED`.
+
+### Inbound Actions
+- `commerce:order:created`: Automatically initiates the payment flow.
+- `commerce:order:refund-requested`: Automatically initiates the refund gateway call.
+
+## Security
+- **Strict Isolation**: No raw card data ever touches the Gravito core. All sensitive data is handled via Gateway Tokens (Stripe Tokens/Secrets).
+- **Idempotency**: All `pay()` and `refund()` calls require an idempotency key to prevent double-charging.

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,238 @@
+// src/index.ts
+import { ServiceProvider } from "@gravito/core";
+
+// src/Application/UseCases/ProcessPayment.ts
+import { UseCase } from "@gravito/enterprise";
+
+// src/Domain/Entities/Transaction.ts
+import { Entity } from "@gravito/enterprise";
+var Transaction = class _Transaction extends Entity {
+  constructor(id, props) {
+    super(id);
+    this.props = props;
+  }
+  static create(id, props) {
+    return new _Transaction(id, {
+      ...props,
+      status: "pending" /* PENDING */,
+      metadata: {},
+      createdAt: /* @__PURE__ */ new Date()
+    });
+  }
+  authorize(gatewayId) {
+    if (this.props.status !== "pending" /* PENDING */) {
+      throw new Error("Only pending transactions can be authorized");
+    }
+    this.props.status = "authorized" /* AUTHORIZED */;
+    this.props.gatewayTransactionId = gatewayId;
+  }
+  capture() {
+    if (this.props.status !== "authorized" /* AUTHORIZED */) {
+      throw new Error("Only authorized transactions can be captured");
+    }
+    this.props.status = "captured" /* CAPTURED */;
+  }
+  refund() {
+    if (this.props.status !== "captured" /* CAPTURED */) {
+      throw new Error("Only captured transactions can be refunded");
+    }
+    this.props.status = "refunded" /* REFUNDED */;
+  }
+  fail(reason) {
+    this.props.status = "failed" /* FAILED */;
+    this.props.metadata.failReason = reason;
+  }
+  get orderId() {
+    return this.props.orderId;
+  }
+  get amount() {
+    return this.props.amount;
+  }
+  get status() {
+    return this.props.status;
+  }
+  get gateway() {
+    return this.props.gateway;
+  }
+};
+
+// src/Application/UseCases/ProcessPayment.ts
+var ProcessPayment = class extends UseCase {
+  constructor(manager) {
+    super();
+    this.manager = manager;
+  }
+  async execute(input) {
+    const transaction = Transaction.create(crypto.randomUUID(), {
+      orderId: input.orderId,
+      amount: input.amount,
+      currency: input.currency,
+      gateway: input.gateway || "default"
+    });
+    const gateway = this.manager.driver(input.gateway);
+    const intent = await gateway.createIntent(transaction);
+    transaction.authorize(intent.gatewayTransactionId);
+    return intent;
+  }
+};
+
+// src/Application/UseCases/RefundPayment.ts
+import { UseCase as UseCase2 } from "@gravito/enterprise";
+var RefundPayment = class extends UseCase2 {
+  constructor(gateway) {
+    super();
+    this.gateway = gateway;
+  }
+  async execute(input) {
+    console.log(`[Payment] Processing refund for transaction: ${input.gatewayTransactionId}`);
+    return await this.gateway.refund(input.gatewayTransactionId, input.amount);
+  }
+};
+
+// src/Infrastructure/Gateways/StripeGateway.ts
+import Stripe from "stripe";
+var StripeGateway = class {
+  stripe;
+  constructor(apiKey) {
+    this.stripe = new Stripe(apiKey, {
+      apiVersion: "2025-01-27"
+    });
+  }
+  getName() {
+    return "stripe";
+  }
+  async createIntent(transaction) {
+    const rawProps = transaction.props;
+    const intent = await this.stripe.paymentIntents.create({
+      amount: Math.round(transaction.amount * 100),
+      currency: rawProps.currency.toLowerCase(),
+      metadata: {
+        orderId: transaction.orderId,
+        transactionId: transaction.id
+      },
+      automatic_payment_methods: {
+        enabled: true
+      }
+    });
+    return {
+      gatewayTransactionId: intent.id,
+      clientSecret: intent.client_secret || "",
+      status: intent.status
+    };
+  }
+  async capture(gatewayTransactionId) {
+    const intent = await this.stripe.paymentIntents.capture(gatewayTransactionId);
+    return intent.status === "succeeded";
+  }
+  async refund(gatewayTransactionId, amount) {
+    const refund = await this.stripe.refunds.create({
+      payment_intent: gatewayTransactionId,
+      ...amount && { amount: Math.round(amount * 100) }
+    });
+    return refund.status === "succeeded";
+  }
+};
+
+// src/Infrastructure/PaymentManager.ts
+var PaymentManager = class {
+  constructor(core) {
+    this.core = core;
+  }
+  drivers = /* @__PURE__ */ new Map();
+  /**
+   * 註冊金流驅動器 (這就是日後掛載 ECPay, LINE Pay 的入口)
+   */
+  extend(name, resolver) {
+    this.core.logger.info(`[PaymentManager] Driver registered: ${name}`);
+    this.drivers.set(name, resolver);
+  }
+  /**
+   * 取得指定或預設的驅動器
+   */
+  driver(name) {
+    const driverName = name || this.core.config.get("payment.default", "stripe");
+    const resolver = this.drivers.get(driverName);
+    if (!resolver) {
+      throw new Error(
+        `Payment driver [${driverName}] is not registered. Did you forget to mount the gateway satellite?`
+      );
+    }
+    return resolver();
+  }
+};
+
+// src/Interface/Http/Controllers/StripeWebhookController.ts
+import Stripe2 from "stripe";
+var StripeWebhookController = class {
+  async handle(c) {
+    const core = c.get("core");
+    const stripeKey = core.config.get("payment.stripe.secret") || "";
+    const webhookSecret = core.config.get("payment.stripe.webhook_secret") || "";
+    const stripe = new Stripe2(stripeKey);
+    const signature = c.req.header("stripe-signature") || "";
+    try {
+      const body = await c.req.text();
+      const event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
+      if (event.type === "payment_intent.succeeded") {
+        const intent = event.data.object;
+        core.logger.info(`[Payment] Webhook: Payment succeeded for ${intent.id}`);
+        await core.hooks.doAction("payment:succeeded", {
+          gatewayTransactionId: intent.id,
+          orderId: intent.metadata.orderId,
+          amount: intent.amount / 100
+        });
+      }
+      return c.json({ received: true });
+    } catch (err) {
+      core.logger.error(`[Payment] Webhook Error: ${err.message}`);
+      return c.json({ error: "Webhook signature verification failed" }, 400);
+    }
+  }
+};
+
+// src/index.ts
+var PaymentServiceProvider = class extends ServiceProvider {
+  register(container) {
+    container.singleton("payment.manager", (_c) => new PaymentManager(this.core));
+    container.singleton("payment.process", (c) => {
+      return new ProcessPayment(c.make("payment.manager"));
+    });
+    container.singleton("payment.refund", (c) => {
+      return new RefundPayment(c.make("payment.manager"));
+    });
+  }
+  boot() {
+    const core = this.core;
+    if (!core) {
+      return;
+    }
+    const manager = core.container.make("payment.manager");
+    manager.extend("stripe", () => {
+      const apiKey = core.config.get("payment.stripe.secret") || "mock_key";
+      return new StripeGateway(apiKey);
+    });
+    const webhookCtrl = new StripeWebhookController();
+    core.router.post("/webhooks/payment/stripe", (c) => webhookCtrl.handle(c));
+    core.logger.info("\u{1F6F0}\uFE0F Satellite Payment is operational (Manager Ready)");
+    core.hooks.addAction("commerce:order:created", async (payload) => {
+      const processPayment = core.container.make("payment.process");
+      try {
+        const intent = await processPayment.execute({
+          orderId: payload.order.id,
+          amount: payload.order.totalAmount,
+          currency: payload.order.currency
+          // gateway: 'stripe' // 可以由配置或 Payload 決定
+        });
+        await core.hooks.doAction("payment:intent:ready", { orderId: payload.order.id, intent });
+      } catch (error) {
+        core.logger.error(`[Payment] Process error: ${error.message}`);
+      }
+    });
+    core.hooks.addAction("payment:succeeded", async (payload) => {
+      core.logger.info(`[Payment] Order confirmed as PAID: ${payload.orderId}`);
+    });
+  }
+};
+export {
+  PaymentServiceProvider
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@gravito/satellite-payment",
+  "version": "0.1.1",
+  "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"
+  },
+  "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/CreatePayment.ts

@@ -0,0 +1,22 @@
+import { UseCase } from '@gravito/enterprise'
+import type { IPaymentRepository } from '../../Domain/Contracts/IPaymentRepository'
+import { Payment } from '../../Domain/Entities/Payment'
+
+export interface CreatePaymentInput {
+  name: string
+}
+
+export class CreatePayment extends UseCase<CreatePaymentInput, string> {
+  constructor(private repository: IPaymentRepository) {
+    super()
+  }
+
+  async execute(input: CreatePaymentInput): Promise<string> {
+    const id = crypto.randomUUID()
+    const entity = Payment.create(id, input.name)
+
+    await this.repository.save(entity)
+
+    return id
+  }
+}

package/src/Application/UseCases/ProcessPayment.ts

@@ -0,0 +1,34 @@
+import { UseCase } from '@gravito/enterprise'
+import type { PaymentIntent } from '../../Domain/Contracts/IPaymentGateway'
+import { Transaction } from '../../Domain/Entities/Transaction'
+import type { PaymentManager } from '../../Infrastructure/PaymentManager'
+
+export interface ProcessPaymentInput {
+  orderId: string
+  amount: number
+  currency: string
+  gateway?: string // 現在可以動態指定
+}
+
+export class ProcessPayment extends UseCase<ProcessPaymentInput, PaymentIntent> {
+  constructor(private manager: PaymentManager) {
+    super()
+  }
+
+  async execute(input: ProcessPaymentInput): Promise<PaymentIntent> {
+    const transaction = Transaction.create(crypto.randomUUID(), {
+      orderId: input.orderId,
+      amount: input.amount,
+      currency: input.currency,
+      gateway: input.gateway || 'default',
+    })
+
+    // 從 Manager 取得指定的金流驅動器
+    const gateway = this.manager.driver(input.gateway)
+    const intent = await gateway.createIntent(transaction)
+
+    transaction.authorize(intent.gatewayTransactionId)
+
+    return intent
+  }
+}

package/src/Application/UseCases/RefundPayment.ts

@@ -0,0 +1,18 @@
+import { UseCase } from '@gravito/enterprise'
+import type { IPaymentGateway } from '../../Domain/Contracts/IPaymentGateway'
+
+export interface RefundPaymentInput {
+  gatewayTransactionId: string
+  amount?: number
+}
+
+export class RefundPayment extends UseCase<RefundPaymentInput, boolean> {
+  constructor(private gateway: IPaymentGateway) {
+    super()
+  }
+
+  async execute(input: RefundPaymentInput): Promise<boolean> {
+    console.log(`[Payment] Processing refund for transaction: ${input.gatewayTransactionId}`)
+    return await this.gateway.refund(input.gatewayTransactionId, input.amount)
+  }
+}

package/src/Domain/Contracts/IPaymentGateway.ts

@@ -0,0 +1,26 @@
+import type { Transaction } from '../Entities/Transaction'
+
+export interface PaymentIntent {
+  gatewayTransactionId: string
+  clientSecret: string // 用於前端付款（如 Stripe Elements）
+  status: string
+}
+
+export interface IPaymentGateway {
+  getName(): string
+
+  /**
+   * 建立支付意向 (Create Intent)
+   */
+  createIntent(transaction: Transaction): Promise<PaymentIntent>
+
+  /**
+   * 清算授權金額 (Capture)
+   */
+  capture(gatewayTransactionId: string): Promise<boolean>
+
+  /**
+   * 退款 (Refund)
+   */
+  refund(gatewayTransactionId: string, amount?: number): Promise<boolean>
+}

package/src/Domain/Contracts/IPaymentRepository.ts

@@ -0,0 +1,6 @@
+import type { Repository } from '@gravito/enterprise'
+import type { Payment } from '../Entities/Payment'
+
+export interface IPaymentRepository extends Repository<Payment, string> {
+  // Add custom methods here
+}

package/src/Domain/Entities/Payment.ts

@@ -0,0 +1,26 @@
+import { Entity } from '@gravito/enterprise'
+
+export interface PaymentProps {
+  name: string
+  createdAt: Date
+}
+
+export class Payment extends Entity<string> {
+  constructor(
+    id: string,
+    private props: PaymentProps
+  ) {
+    super(id)
+  }
+
+  static create(id: string, name: string): Payment {
+    return new Payment(id, {
+      name,
+      createdAt: new Date(),
+    })
+  }
+
+  get name() {
+    return this.props.name
+  }
+}

package/src/Domain/Entities/Transaction.ts

@@ -0,0 +1,81 @@
+import { Entity } from '@gravito/enterprise'
+
+export enum TransactionStatus {
+  PENDING = 'pending',
+  AUTHORIZED = 'authorized',
+  CAPTURED = 'captured',
+  FAILED = 'failed',
+  REFUNDED = 'refunded',
+}
+
+export interface TransactionProps {
+  orderId: string
+  amount: number
+  currency: string
+  gateway: string
+  gatewayTransactionId?: string
+  status: TransactionStatus
+  metadata: Record<string, any>
+  createdAt: Date
+}
+
+export class Transaction extends Entity<string> {
+  constructor(
+    id: string,
+    private props: TransactionProps
+  ) {
+    super(id)
+  }
+
+  static create(
+    id: string,
+    props: Omit<TransactionProps, 'status' | 'createdAt' | 'metadata'>
+  ): Transaction {
+    return new Transaction(id, {
+      ...props,
+      status: TransactionStatus.PENDING,
+      metadata: {},
+      createdAt: new Date(),
+    })
+  }
+
+  authorize(gatewayId: string): void {
+    if (this.props.status !== TransactionStatus.PENDING) {
+      throw new Error('Only pending transactions can be authorized')
+    }
+    this.props.status = TransactionStatus.AUTHORIZED
+    this.props.gatewayTransactionId = gatewayId
+  }
+
+  capture(): void {
+    if (this.props.status !== TransactionStatus.AUTHORIZED) {
+      throw new Error('Only authorized transactions can be captured')
+    }
+    this.props.status = TransactionStatus.CAPTURED
+  }
+
+  refund(): void {
+    if (this.props.status !== TransactionStatus.CAPTURED) {
+      throw new Error('Only captured transactions can be refunded')
+    }
+    this.props.status = TransactionStatus.REFUNDED
+  }
+
+  fail(reason: string): void {
+    this.props.status = TransactionStatus.FAILED
+    this.props.metadata.failReason = reason
+  }
+
+  get orderId() {
+    return this.props.orderId
+  }
+  get amount() {
+    return this.props.amount
+  }
+  get status() {
+    return this.props.status
+  }
+  get gateway() {
+    return this.props.gateway
+  }
+}

package/src/Infrastructure/Gateways/StripeGateway.ts

@@ -0,0 +1,53 @@
+import Stripe from 'stripe'
+import type { IPaymentGateway, PaymentIntent } from '../../Domain/Contracts/IPaymentGateway'
+import type { Transaction } from '../../Domain/Entities/Transaction'
+
+export class StripeGateway implements IPaymentGateway {
+  private stripe: Stripe
+
+  constructor(apiKey: string) {
+    this.stripe = new Stripe(apiKey, {
+      apiVersion: '2025-01-27' as any,
+    })
+  }
+
+  getName(): string {
+    return 'stripe'
+  }
+
+  async createIntent(transaction: Transaction): Promise<PaymentIntent> {
+    // 透過 any 訪問私有屬性以解決跨包訪問問題
+    const rawProps = (transaction as any).props
+
+    const intent = await this.stripe.paymentIntents.create({
+      amount: Math.round(transaction.amount * 100),
+      currency: rawProps.currency.toLowerCase(),
+      metadata: {
+        orderId: transaction.orderId,
+        transactionId: transaction.id,
+      },
+      automatic_payment_methods: {
+        enabled: true,
+      },
+    })
+
+    return {
+      gatewayTransactionId: intent.id,
+      clientSecret: intent.client_secret || '',
+      status: intent.status,
+    }
+  }
+
+  async capture(gatewayTransactionId: string): Promise<boolean> {
+    const intent = await this.stripe.paymentIntents.capture(gatewayTransactionId)
+    return intent.status === 'succeeded'
+  }
+
+  async refund(gatewayTransactionId: string, amount?: number): Promise<boolean> {
+    const refund = await this.stripe.refunds.create({
+      payment_intent: gatewayTransactionId,
+      ...(amount && { amount: Math.round(amount * 100) }),
+    })
+    return refund.status === 'succeeded'
+  }
+}

package/src/Infrastructure/PaymentManager.ts

@@ -0,0 +1,32 @@
+import type { PlanetCore } from '@gravito/core'
+import type { IPaymentGateway } from '../Domain/Contracts/IPaymentGateway'
+
+export class PaymentManager {
+  private drivers = new Map<string, () => IPaymentGateway>()
+
+  constructor(private core: PlanetCore) {}
+
+  /**
+   * 註冊金流驅動器 (這就是日後掛載 ECPay, LINE Pay 的入口)
+   */
+  extend(name: string, resolver: () => IPaymentGateway): void {
+    this.core.logger.info(`[PaymentManager] Driver registered: ${name}`)
+    this.drivers.set(name, resolver)
+  }
+
+  /**
+   * 取得指定或預設的驅動器
+   */
+  driver(name?: string): IPaymentGateway {
+    const driverName = name || this.core.config.get<string>('payment.default', 'stripe')
+    const resolver = this.drivers.get(driverName)
+
+    if (!resolver) {
+      throw new Error(
+        `Payment driver [${driverName}] is not registered. Did you forget to mount the gateway satellite?`
+      )
+    }
+
+    return resolver()
+  }
+}

package/src/Infrastructure/Persistence/AtlasPaymentRepository.ts

@@ -0,0 +1,24 @@
+import type { IPaymentRepository } from '../../Domain/Contracts/IPaymentRepository'
+import type { Payment } from '../../Domain/Entities/Payment'
+
+export class AtlasPaymentRepository implements IPaymentRepository {
+  async save(entity: Payment): Promise<void> {
+    // Dogfooding: Use @gravito/atlas for persistence
+    console.log('[Atlas] Saving entity:', entity.id)
+    // await DB.table('payments').insert({ ... })
+  }
+
+  async findById(_id: string): Promise<Payment | null> {
+    return null
+  }
+
+  async findAll(): Promise<Payment[]> {
+    return []
+  }
+
+  async delete(_id: string): Promise<void> {}
+
+  async exists(_id: string): Promise<boolean> {
+    return false
+  }
+}

package/src/Interface/Http/Controllers/StripeWebhookController.ts

@@ -0,0 +1,34 @@
+import type { GravitoContext, PlanetCore } from '@gravito/core'
+import Stripe from 'stripe'
+
+export class StripeWebhookController {
+  async handle(c: GravitoContext) {
+    const core = c.get('core') as PlanetCore
+    const stripeKey = core.config.get<string>('payment.stripe.secret') || ''
+    const webhookSecret = core.config.get<string>('payment.stripe.webhook_secret') || ''
+
+    const stripe = new Stripe(stripeKey)
+    const signature = c.req.header('stripe-signature') || ''
+
+    try {
+      const body = await c.req.text()
+      const event = stripe.webhooks.constructEvent(body, signature, webhookSecret)
+
+      if (event.type === 'payment_intent.succeeded') {
+        const intent = event.data.object as Stripe.PaymentIntent
+        core.logger.info(`[Payment] Webhook: Payment succeeded for ${intent.id}`)
+
+        await core.hooks.doAction('payment:succeeded', {
+          gatewayTransactionId: intent.id,
+          orderId: intent.metadata.orderId,
+          amount: intent.amount / 100,
+        })
+      }
+
+      return c.json({ received: true })
+    } catch (err: any) {
+      core.logger.error(`[Payment] Webhook Error: ${err.message}`)
+      return c.json({ error: 'Webhook signature verification failed' }, 400)
+    }
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,4 @@
+interface ImportMeta {
+  readonly dir: string
+  readonly path: string
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+import type { Container, GravitoContext } from '@gravito/core'
+import { ServiceProvider } from '@gravito/core'
+import { ProcessPayment } from './Application/UseCases/ProcessPayment'
+import { RefundPayment } from './Application/UseCases/RefundPayment'
+import { StripeGateway } from './Infrastructure/Gateways/StripeGateway'
+import { PaymentManager } from './Infrastructure/PaymentManager'
+import { StripeWebhookController } from './Interface/Http/Controllers/StripeWebhookController'
+
+export class PaymentServiceProvider extends ServiceProvider {
+  register(container: Container): void {
+    // 1. 綁定管理器
+    container.singleton('payment.manager', (_c) => new PaymentManager(this.core!))
+
+    // 2. 綁定 UseCases (傳入 Manager 而非具體 Gateway)
+    container.singleton('payment.process', (c) => {
+      return new ProcessPayment(c.make('payment.manager'))
+    })
+
+    container.singleton('payment.refund', (c) => {
+      return new RefundPayment(c.make('payment.manager'))
+    })
+  }
+
+  override boot(): void {
+    const core = this.core
+    if (!core) {
+      return
+    }
+
+    const manager = core.container.make<PaymentManager>('payment.manager')
+
+    // 🌟 註冊 Stripe 驅動器 (這就是「掛載」動作)
+    // 雖然代碼在 Infrastructure 裡，但只有這裡被呼叫時才會建立實例
+    manager.extend('stripe', () => {
+      const apiKey = core.config.get<string>('payment.stripe.secret') || 'mock_key'
+      return new StripeGateway(apiKey)
+    })
+
+    const webhookCtrl = new StripeWebhookController()
+    core.router.post('/webhooks/payment/stripe', (c: GravitoContext) => webhookCtrl.handle(c))
+
+    core.logger.info('🛰️ Satellite Payment is operational (Manager Ready)')
+
+    /**
+     * GASS 聯動：監聽訂單建立
+     */
+    core.hooks.addAction('commerce:order:created', async (payload: any) => {
+      const processPayment = core.container.make<ProcessPayment>('payment.process')
+      try {
+        const intent = await processPayment.execute({
+          orderId: payload.order.id,
+          amount: payload.order.totalAmount,
+          currency: payload.order.currency,
+          // gateway: 'stripe' // 可以由配置或 Payload 決定
+        })
+        await core.hooks.doAction('payment:intent:ready', { orderId: payload.order.id, intent })
+      } catch (error: any) {
+        core.logger.error(`[Payment] Process error: ${error.message}`)
+      }
+    })
+
+    core.hooks.addAction('payment:succeeded', async (payload: any) => {
+      core.logger.info(`[Payment] Order confirmed as PAID: ${payload.orderId}`)
+    })
+  }
+}

package/src/manifest.json

@@ -0,0 +1,15 @@
+{
+  "name": "payment",
+  "id": "payment",
+  "version": "0.1.0",
+  "description": "A Gravito Satellite",
+  "capabilities": [
+    "create-payment"
+  ],
+  "requirements": [
+    "cache"
+  ],
+  "hooks": [
+    "payment:created"
+  ]
+}

package/tests/unit.test.ts

@@ -0,0 +1,7 @@
+import { describe, expect, it } from 'bun:test'
+
+describe('Payment', () => {
+  it('should work', () => {
+    expect(true).toBe(true)
+  })
+})

package/tsconfig.json

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