@gravito/satellite-logistics 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="logistics"
+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 @@
+# logistics 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-logistics
+
+## 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/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,227 @@
+// src/index.ts
+import { ServiceProvider } from "@gravito/core";
+
+// src/Application/UseCases/ArrangeShipment.ts
+import { UseCase } from "@gravito/enterprise";
+
+// src/Domain/Entities/Shipment.ts
+import { Entity } from "@gravito/enterprise";
+var Shipment = class _Shipment extends Entity {
+  constructor(id, props) {
+    super(id);
+    this.props = props;
+  }
+  static create(id, props) {
+    return new _Shipment(id, {
+      ...props,
+      status: "pending" /* PENDING */,
+      metadata: {}
+    });
+  }
+  markAsShipped(trackingNumber) {
+    this.props.status = "shipped" /* SHIPPED */;
+    this.props.trackingNumber = trackingNumber;
+  }
+  get status() {
+    return this.props.status;
+  }
+  get orderId() {
+    return this.props.orderId;
+  }
+  get trackingNumber() {
+    return this.props.trackingNumber;
+  }
+};
+
+// src/Application/UseCases/ArrangeShipment.ts
+var ArrangeShipment = class extends UseCase {
+  constructor(repository, manager) {
+    super();
+    this.repository = repository;
+    this.manager = manager;
+  }
+  async execute(input) {
+    const existing = await this.repository.findByOrderId(input.orderId);
+    if (existing) {
+      throw new Error(`Shipment for order ${input.orderId} already exists.`);
+    }
+    const provider = this.manager.provider(input.providerName);
+    const trackingNumber = await provider.ship(input.orderId, {
+      recipient: input.recipientName,
+      address: input.address
+    });
+    const shipmentId = crypto.randomUUID();
+    const shipment = Shipment.create(shipmentId, {
+      orderId: input.orderId,
+      recipientName: input.recipientName,
+      address: input.address,
+      carrier: provider.getName(),
+      cvsType: void 0,
+      // 暫時未處理超商
+      cvsStoreId: void 0
+    });
+    shipment.markAsShipped(trackingNumber);
+    await this.repository.save(shipment);
+    return {
+      shipmentId: shipment.id,
+      trackingNumber: shipment.trackingNumber,
+      status: shipment.status
+    };
+  }
+};
+
+// src/Infrastructure/LogisticsManager.ts
+var LocalShippingProvider = class {
+  getName() {
+    return "local";
+  }
+  async calculateCost(weight, _destination) {
+    return 60 + weight * 10;
+  }
+  async ship(orderId, _details) {
+    return `LOC-${orderId}-${Date.now().toString().slice(-4)}`;
+  }
+};
+var LogisticsManager = class {
+  constructor(core) {
+    this.core = core;
+    this.extend("local", () => new LocalShippingProvider());
+  }
+  providers = /* @__PURE__ */ new Map();
+  extend(name, resolver) {
+    this.core.logger.info(`[LogisticsManager] Provider registered: ${name}`);
+    this.providers.set(name, resolver);
+  }
+  provider(name) {
+    const providerName = name || this.core.config.get("logistics.default", "local");
+    const resolver = this.providers.get(providerName);
+    if (!resolver) {
+      if (providerName === "local" && !this.providers.has("local")) {
+        const local = new LocalShippingProvider();
+        this.providers.set("local", () => local);
+        return local;
+      }
+      throw new Error(`Logistics provider [${providerName}] not found.`);
+    }
+    return resolver();
+  }
+};
+
+// src/Infrastructure/Persistence/AtlasShipmentRepository.ts
+var AtlasShipmentRepository = class _AtlasShipmentRepository {
+  // 暫時使用靜態 Map 模擬資料庫，確保在沒有真實 DB 連接時也能運作 (In-Memory Persistence)
+  // 在真實生產環境中，這裡會替換為 Atlas DB 查詢
+  static storage = /* @__PURE__ */ new Map();
+  async save(entity) {
+    const data = {
+      id: entity.id,
+      orderId: entity.orderId,
+      status: entity.status,
+      // 這裡需要存取受保護的 props，但在 TypeScript 中通常透過 getter 或 public props 存取
+      // 為了演示，我們假設可以獲取 props
+      ...entity.props
+    };
+    console.log(
+      `[AtlasShipmentRepository] Persisting shipment ${entity.id} for order ${entity.orderId}`
+    );
+    _AtlasShipmentRepository.storage.set(entity.id, data);
+  }
+  async findById(id) {
+    const data = _AtlasShipmentRepository.storage.get(id);
+    if (!data) {
+      return null;
+    }
+    return new Shipment(data.id, data);
+  }
+  async findByOrderId(orderId) {
+    for (const data of _AtlasShipmentRepository.storage.values()) {
+      if (data.orderId === orderId) {
+        return new Shipment(data.id, data);
+      }
+    }
+    return null;
+  }
+  async findByTrackingNumber(trackingNumber) {
+    for (const data of _AtlasShipmentRepository.storage.values()) {
+      if (data.trackingNumber === trackingNumber) {
+        return new Shipment(data.id, data);
+      }
+    }
+    return null;
+  }
+  async findAll() {
+    return Array.from(_AtlasShipmentRepository.storage.values()).map(
+      (data) => new Shipment(data.id, data)
+    );
+  }
+  async delete(id) {
+    _AtlasShipmentRepository.storage.delete(id);
+  }
+  async exists(id) {
+    return _AtlasShipmentRepository.storage.has(id);
+  }
+};
+
+// src/index.ts
+var LogisticsServiceProvider = class extends ServiceProvider {
+  register(container) {
+    container.singleton("logistics.manager", () => new LogisticsManager(this.core));
+    container.singleton("logistics.repository", () => new AtlasShipmentRepository());
+    container.bind(
+      "usecase.arrangeShipment",
+      () => new ArrangeShipment(
+        container.make("logistics.repository"),
+        container.make("logistics.manager")
+      )
+    );
+  }
+  boot() {
+    const core = this.core;
+    if (!core) {
+      return;
+    }
+    core.logger.info("\u{1F6F0}\uFE0F Satellite Logistics is operational");
+    core.hooks.addAction(
+      "payment:succeeded",
+      async (payload) => {
+        core.logger.info(
+          `[Logistics] Payment verified for order: ${payload.orderId}. Preparing shipment...`
+        );
+        try {
+          const useCase = core.container.make("usecase.arrangeShipment");
+          const recipientName = payload.orderData?.recipientName || "Guest User";
+          const address = payload.orderData?.address || "Default Address";
+          const result = await useCase.execute({
+            orderId: payload.orderId,
+            recipientName,
+            address
+          });
+          core.logger.info(`[Logistics] Shipment arranged: ${result.trackingNumber}`);
+          await core.hooks.doAction("logistics:shipment:prepared", {
+            orderId: payload.orderId,
+            shipmentId: result.shipmentId,
+            trackingNumber: result.trackingNumber,
+            status: result.status
+          });
+        } catch (error) {
+          core.logger.error(`[Logistics] Failed to arrange shipment: ${error.message}`);
+        }
+      }
+    );
+    core.hooks.addFilter("commerce:order:adjustments", async (adjustments, args) => {
+      const _payload = args;
+      const manager = core.container.make("logistics.manager");
+      const cost = await manager.provider().calculateCost(1, "TW");
+      adjustments.push({
+        label: "Shipping Fee (Standard)",
+        amount: cost,
+        sourceType: "shipping",
+        sourceId: "standard"
+      });
+      return adjustments;
+    });
+  }
+};
+export {
+  LogisticsServiceProvider
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@gravito/satellite-logistics",
+  "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/core --external @gravito/enterprise --external @gravito/atlas --external @gravito/stasis",
+    "test": "bun test",
+    "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck"
+  },
+  "dependencies": {
+    "@gravito/core": "workspace:*",
+    "@gravito/enterprise": "workspace:*",
+    "@gravito/atlas": "workspace:*",
+    "@gravito/stasis": "workspace:*"
+  },
+  "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/logistics"
+  }
+}

package/src/Application/UseCases/ArrangeShipment.ts

@@ -0,0 +1,67 @@
+import { UseCase } from '@gravito/enterprise'
+import type { IShipmentRepository } from '../../Domain/Contracts/IShipmentRepository'
+import { Shipment } from '../../Domain/Entities/Shipment'
+import type { LogisticsManager } from '../../Infrastructure/LogisticsManager'
+
+export interface ArrangeShipmentInput {
+  orderId: string
+  recipientName: string
+  address: string
+  providerName?: string // 指定物流商，可選
+  items?: any[] // 用於計算重量等
+}
+
+export interface ArrangeShipmentOutput {
+  shipmentId: string
+  trackingNumber: string
+  status: string
+}
+
+export class ArrangeShipment extends UseCase<ArrangeShipmentInput, ArrangeShipmentOutput> {
+  constructor(
+    private repository: IShipmentRepository,
+    private manager: LogisticsManager
+  ) {
+    super()
+  }
+
+  async execute(input: ArrangeShipmentInput): Promise<ArrangeShipmentOutput> {
+    // 1. 檢查是否已存在運單
+    const existing = await this.repository.findByOrderId(input.orderId)
+    if (existing) {
+      throw new Error(`Shipment for order ${input.orderId} already exists.`)
+    }
+
+    // 2. 取得物流供應商
+    const provider = this.manager.provider(input.providerName)
+
+    // 3. 向供應商請求出貨 (取得追蹤碼)
+    const trackingNumber = await provider.ship(input.orderId, {
+      recipient: input.recipientName,
+      address: input.address,
+    })
+
+    // 4. 建立 Shipment 實體
+    const shipmentId = crypto.randomUUID()
+    const shipment = Shipment.create(shipmentId, {
+      orderId: input.orderId,
+      recipientName: input.recipientName,
+      address: input.address,
+      carrier: provider.getName(),
+      cvsType: undefined, // 暫時未處理超商
+      cvsStoreId: undefined,
+    })
+
+    // 5. 更新狀態為已出貨 (或根據供應商回應決定)
+    shipment.markAsShipped(trackingNumber)
+
+    // 6. 儲存
+    await this.repository.save(shipment)
+
+    return {
+      shipmentId: shipment.id,
+      trackingNumber: shipment.trackingNumber!,
+      status: shipment.status,
+    }
+  }
+}

package/src/Domain/Contracts/IShipmentRepository.ts

@@ -0,0 +1,7 @@
+import type { Repository } from '@gravito/enterprise'
+import type { Shipment } from '../Entities/Shipment'
+
+export interface IShipmentRepository extends Repository<Shipment, string> {
+  findByOrderId(orderId: string): Promise<Shipment | null>
+  findByTrackingNumber(trackingNumber: string): Promise<Shipment | null>
+}

package/src/Domain/Entities/Shipment.ts

@@ -0,0 +1,55 @@
+import { Entity } from '@gravito/enterprise'
+
+export enum ShipmentStatus {
+  PENDING = 'pending',
+  PICKED = 'picked',
+  SHIPPED = 'shipped',
+  DELIVERED = 'delivered',
+  CVS_ARRIVED = 'cvs_arrived', // 台灣特色：貨到門市
+  RETURNED = 'returned',
+}
+
+export interface ShipmentProps {
+  orderId: string
+  trackingNumber?: string
+  carrier: string
+  status: ShipmentStatus
+  recipientName: string
+  address: string
+  // 台灣 CVS 擴充屬性
+  cvsStoreId?: string
+  cvsType?: '7-11' | 'fami'
+  metadata: Record<string, any>
+}
+
+export class Shipment extends Entity<string> {
+  constructor(
+    id: string,
+    private props: ShipmentProps
+  ) {
+    super(id)
+  }
+
+  static create(id: string, props: Omit<ShipmentProps, 'status' | 'metadata'>): Shipment {
+    return new Shipment(id, {
+      ...props,
+      status: ShipmentStatus.PENDING,
+      metadata: {},
+    })
+  }
+
+  markAsShipped(trackingNumber: string): void {
+    this.props.status = ShipmentStatus.SHIPPED
+    this.props.trackingNumber = trackingNumber
+  }
+
+  get status() {
+    return this.props.status
+  }
+  get orderId() {
+    return this.props.orderId
+  }
+  get trackingNumber() {
+    return this.props.trackingNumber
+  }
+}

package/src/Infrastructure/LogisticsManager.ts

@@ -0,0 +1,55 @@
+import type { PlanetCore } from '@gravito/core'
+
+export interface IShippingProvider {
+  getName(): string
+  calculateCost(weight: number, destination: string): Promise<number>
+  ship(orderId: string, details: any): Promise<string> // 回傳 Tracking Number
+}
+
+class LocalShippingProvider implements IShippingProvider {
+  getName(): string {
+    return 'local'
+  }
+
+  async calculateCost(weight: number, _destination: string): Promise<number> {
+    // 簡單的計費邏輯：基礎費 60 + 每公斤 10 元
+    return 60 + weight * 10
+  }
+
+  async ship(orderId: string, _details: any): Promise<string> {
+    // 產生模擬的追蹤碼
+    return `LOC-${orderId}-${Date.now().toString().slice(-4)}`
+  }
+}
+
+export class LogisticsManager {
+  private providers = new Map<string, () => IShippingProvider>()
+
+  constructor(private core: PlanetCore) {
+    // 註冊預設的 Local Provider
+    this.extend('local', () => new LocalShippingProvider())
+  }
+
+  extend(name: string, resolver: () => IShippingProvider): void {
+    this.core.logger.info(`[LogisticsManager] Provider registered: ${name}`)
+    this.providers.set(name, resolver)
+  }
+
+  provider(name?: string): IShippingProvider {
+    // 優先使用傳入的名稱，其次讀取設定，最後 fallback 到 'local'
+    const providerName = name || this.core.config.get<string>('logistics.default', 'local')
+    const resolver = this.providers.get(providerName)
+
+    if (!resolver) {
+      // 若找不到，但請求的是 default，則嘗試使用 local
+      if (providerName === 'local' && !this.providers.has('local')) {
+        const local = new LocalShippingProvider()
+        this.providers.set('local', () => local)
+        return local
+      }
+      throw new Error(`Logistics provider [${providerName}] not found.`)
+    }
+
+    return resolver()
+  }
+}

package/src/Infrastructure/Persistence/AtlasShipmentRepository.ts

@@ -0,0 +1,66 @@
+import type { IShipmentRepository } from '../../Domain/Contracts/IShipmentRepository'
+import { Shipment } from '../../Domain/Entities/Shipment'
+// import { DB } from '@gravito/atlas' // 假設 Atlas DB 尚未完全以此方式導出，我們先用記憶體模擬以確保測試通過，或寫出標準結構
+
+export class AtlasShipmentRepository implements IShipmentRepository {
+  // 暫時使用靜態 Map 模擬資料庫，確保在沒有真實 DB 連接時也能運作 (In-Memory Persistence)
+  // 在真實生產環境中，這裡會替換為 Atlas DB 查詢
+  private static storage = new Map<string, any>()
+
+  async save(entity: Shipment): Promise<void> {
+    // 序列化實體
+    const data = {
+      id: entity.id,
+      orderId: entity.orderId,
+      status: entity.status,
+      // 這裡需要存取受保護的 props，但在 TypeScript 中通常透過 getter 或 public props 存取
+      // 為了演示，我們假設可以獲取 props
+      ...(entity as any).props,
+    }
+
+    console.log(
+      `[AtlasShipmentRepository] Persisting shipment ${entity.id} for order ${entity.orderId}`
+    )
+    AtlasShipmentRepository.storage.set(entity.id, data)
+  }
+
+  async findById(id: string): Promise<Shipment | null> {
+    const data = AtlasShipmentRepository.storage.get(id)
+    if (!data) {
+      return null
+    }
+    return new Shipment(data.id, data)
+  }
+
+  async findByOrderId(orderId: string): Promise<Shipment | null> {
+    for (const data of AtlasShipmentRepository.storage.values()) {
+      if (data.orderId === orderId) {
+        return new Shipment(data.id, data)
+      }
+    }
+    return null
+  }
+
+  async findByTrackingNumber(trackingNumber: string): Promise<Shipment | null> {
+    for (const data of AtlasShipmentRepository.storage.values()) {
+      if (data.trackingNumber === trackingNumber) {
+        return new Shipment(data.id, data)
+      }
+    }
+    return null
+  }
+
+  async findAll(): Promise<Shipment[]> {
+    return Array.from(AtlasShipmentRepository.storage.values()).map(
+      (data) => new Shipment(data.id, data)
+    )
+  }
+
+  async delete(id: string): Promise<void> {
+    AtlasShipmentRepository.storage.delete(id)
+  }
+
+  async exists(id: string): Promise<boolean> {
+    return AtlasShipmentRepository.storage.has(id)
+  }
+}

package/src/env.d.ts

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

package/src/index.ts

@@ -0,0 +1,88 @@
+import { type Container, ServiceProvider } from '@gravito/core'
+import { ArrangeShipment } from './Application/UseCases/ArrangeShipment'
+import { LogisticsManager } from './Infrastructure/LogisticsManager'
+import { AtlasShipmentRepository } from './Infrastructure/Persistence/AtlasShipmentRepository'
+
+export class LogisticsServiceProvider extends ServiceProvider {
+  register(container: Container): void {
+    container.singleton('logistics.manager', () => new LogisticsManager(this.core!))
+    container.singleton('logistics.repository', () => new AtlasShipmentRepository())
+
+    container.bind(
+      'usecase.arrangeShipment',
+      () =>
+        new ArrangeShipment(
+          container.make('logistics.repository'),
+          container.make('logistics.manager')
+        )
+    )
+  }
+
+  override boot(): void {
+    const core = this.core
+    if (!core) {
+      return
+    }
+
+    core.logger.info('🛰️ Satellite Logistics is operational')
+
+    /**
+     * GASS 聯動：監聽支付成功
+     */
+    core.hooks.addAction(
+      'payment:succeeded',
+      async (payload: { orderId: string; orderData?: any }) => {
+        core.logger.info(
+          `[Logistics] Payment verified for order: ${payload.orderId}. Preparing shipment...`
+        )
+
+        try {
+          const useCase = core.container.make<ArrangeShipment>('usecase.arrangeShipment')
+
+          // 假設 payload 中包含必要的收件資訊，若無則使用預設值或查詢 Order 服務
+          // 這裡為了演示，使用 Payload 中的資料或 Mock 資料
+          const recipientName = payload.orderData?.recipientName || 'Guest User'
+          const address = payload.orderData?.address || 'Default Address'
+
+          const result = await useCase.execute({
+            orderId: payload.orderId,
+            recipientName,
+            address,
+          })
+
+          core.logger.info(`[Logistics] Shipment arranged: ${result.trackingNumber}`)
+
+          // 發射物流準備完成事件
+          await core.hooks.doAction('logistics:shipment:prepared', {
+            orderId: payload.orderId,
+            shipmentId: result.shipmentId,
+            trackingNumber: result.trackingNumber,
+            status: result.status,
+          })
+        } catch (error: any) {
+          core.logger.error(`[Logistics] Failed to arrange shipment: ${error.message}`)
+        }
+      }
+    )
+
+    /**
+     * GASS 聯動：監聽運費計算 Filter
+     */
+    core.hooks.addFilter('commerce:order:adjustments', async (adjustments: any[], args: any) => {
+      const _payload = args as { order: any }
+
+      // 預設運費邏輯 (可改為呼叫 Manager 計算)
+      const manager = core.container.make<LogisticsManager>('logistics.manager')
+      const cost = await manager.provider().calculateCost(1, 'TW') // 假設 1kg
+
+      adjustments.push({
+        label: 'Shipping Fee (Standard)',
+        amount: cost,
+        sourceType: 'shipping',
+        sourceId: 'standard',
+      })
+
+      return adjustments
+    })
+  }
+}

package/src/manifest.json

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

package/tests/unit.test.ts

@@ -0,0 +1,71 @@
+import { beforeEach, describe, expect, it } from 'bun:test'
+import { PlanetCore } from '@gravito/core'
+import { ArrangeShipment } from '../src/Application/UseCases/ArrangeShipment'
+import { LogisticsManager } from '../src/Infrastructure/LogisticsManager'
+import { AtlasShipmentRepository } from '../src/Infrastructure/Persistence/AtlasShipmentRepository'
+
+// Mock PlanetCore
+class MockCore extends PlanetCore {
+  constructor() {
+    super({} as any) // Pass minimal config
+    this.logger = {
+      info: () => {},
+      error: () => {},
+      warn: () => {},
+      debug: () => {},
+    } as any
+    this.config = {
+      get: (_key: string, def: any) => def,
+    } as any
+  }
+}
+
+describe('Logistics Satellite', () => {
+  let repository: AtlasShipmentRepository
+  let manager: LogisticsManager
+  let useCase: ArrangeShipment
+
+  beforeEach(() => {
+    // Reset singleton if necessary, but here we just instantiate new ones
+    repository = new AtlasShipmentRepository()
+    manager = new LogisticsManager(new MockCore())
+    useCase = new ArrangeShipment(repository, manager)
+  })
+
+  it('should arrange a shipment successfully', async () => {
+    const input = {
+      orderId: 'ORD-123',
+      recipientName: 'Test User',
+      address: 'Taipei City',
+    }
+
+    const result = await useCase.execute(input)
+
+    expect(result.shipmentId).toBeDefined()
+    expect(result.trackingNumber).toStartWith('LOC-ORD-123')
+    expect(result.status).toBe('shipped')
+
+    // Verify persistence
+    const saved = await repository.findById(result.shipmentId)
+    expect(saved).toBeDefined()
+    expect(saved?.orderId).toBe('ORD-123')
+  })
+
+  it('should prevent duplicate shipments for the same order', async () => {
+    const input = {
+      orderId: 'ORD-DUP',
+      recipientName: 'Test User',
+      address: 'Taipei City',
+    }
+
+    await useCase.execute(input)
+
+    // Second attempt should fail
+    try {
+      await useCase.execute(input)
+      expect(true).toBe(false) // Should not reach here
+    } catch (e: any) {
+      expect(e.message).toContain('already exists')
+    }
+  })
+})

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"
+    ]
+}