| name | logistics-development |
| description | Development guide for @rytass/logistics base package (物流基底套件開發指南). Use when creating new logistics adapters (新增物流 adapter), understanding base interfaces, or extending logistics functionality. Covers LogisticsService, LogisticsInterface, error handling patterns for Taiwan logistics providers. Keywords: logistics adapter, 物流 adapter, 開發指南, CTC, TCAT, 宅配, shipping, delivery
|
Logistics Adapter Development Guide (物流 Adapter 開發指南)
Overview
本指南說明如何基於 @rytass/logistics 基礎套件開發新的物流服務適配器。
Base Package Architecture
@rytass/logistics (Base)
├── LogisticsService<T> # 核心服務介面
├── LogisticsInterface<T> # 配置介面
├── LogisticsBaseStatus # 基礎狀態類型 ('DELIVERED' | 'DELIVERING' | 'SHELVED')
├── LogisticsStatus<T> # 泛型狀態類型
├── LogisticsTraceResponse # 追蹤結果
├── LogisticsStatusHistory # 狀態歷史
├── LogisticsErrorInterface # 錯誤介面
├── LogisticsError # 統一錯誤類別
└── ErrorCode # 錯誤代碼列舉
Core Interfaces
LogisticsService
interface LogisticsService<T extends LogisticsInterface<LogisticsStatus<T>>> {
trace(request: string): Promise<LogisticsTraceResponse<T>[]>;
trace(request: string[]): Promise<LogisticsTraceResponse<T>[]>;
}
LogisticsInterface
interface LogisticsInterface<T = LogisticsBaseStatus> {
reference?: T;
url: string;
}
type LogisticsBaseStatus = 'DELIVERED' | 'DELIVERING' | 'SHELVED';
Response Types
interface LogisticsTraceResponse<K extends LogisticsInterface<LogisticsStatus<K>>> {
logisticsId: string;
statusHistory: LogisticsStatusHistory<K['reference']>[];
}
interface LogisticsStatusHistory<T> {
date: string;
status: T;
}
interface LogisticsErrorInterface {
readonly code: string;
readonly message?: string;
}
Implementing a New Adapter
Step 1: Define Status Types
export type MyLogisticsStatus =
| 'DELIVERED'
| 'DELIVERING'
| 'SHELVED'
| 'PENDING'
| 'CANCELLED';
export interface MyLogisticsInterface<T> extends LogisticsInterface<T> {
apiKey: string;
apiSecret: string;
ignoreNotFound?: boolean;
}
Step 2: Create Status Map
export const MyLogisticsStatusMap: Record<string, MyLogisticsStatus> = {
'已送達': 'DELIVERED',
'配送中': 'DELIVERING',
'待取': 'SHELVED',
'待處理': 'PENDING',
'已取消': 'CANCELLED',
};
Step 3: Implement Service Class
import { LogisticsService, LogisticsTraceResponse, LogisticsError, ErrorCode } from '@rytass/logistics';
import axios from 'axios';
export class MyLogisticsService<T extends MyLogisticsInterface<LogisticsStatus<T>>>
implements LogisticsService<T> {
constructor(private readonly configuration: T) {}
async trace(logisticsIds: string | string[]): Promise<LogisticsTraceResponse<T>[]> {
const ids = Array.isArray(logisticsIds) ? logisticsIds : [logisticsIds];
return Promise.all(ids.map(id => this.getLogisticsStatus(id)));
}
private async getLogisticsStatus(trackingId: string): Promise<LogisticsTraceResponse<T>> {
try {
const response = await axios.get(`${this.configuration.url}/track/${trackingId}`, {
headers: {
'X-API-Key': this.configuration.apiKey,
'X-API-Secret': this.configuration.apiSecret,
},
});
if (!response.data.success) {
if (this.configuration.ignoreNotFound) {
return { logisticsId: trackingId, statusHistory: [] };
}
throw new LogisticsError(ErrorCode.NOT_FOUND_ERROR, `Tracking ${trackingId} not found`);
}
return {
logisticsId: trackingId,
statusHistory: this.mapStatusHistory(response.data.history),
};
} catch (error) {
if (error instanceof LogisticsError) throw error;
if (axios.isAxiosError(error)) {
if (error.response?.status === 403) {
throw new LogisticsError(ErrorCode.PERMISSION_DENIED, 'Invalid API credentials');
}
if (error.response?.status === 400) {
throw new LogisticsError(ErrorCode.INVALID_PARAMETER, 'Invalid tracking number');
}
}
throw new LogisticsError(ErrorCode.NOT_IMPLEMENTED, 'Unknown error');
}
}
private mapStatusHistory(history: any[]): LogisticsStatusHistory<T['reference']>[] {
return history.map(item => ({
date: item.timestamp,
status: MyLogisticsStatusMap[item.status] || 'DELIVERING',
}));
}
}
Step 4: Export Default Configuration
export * from './typings';
export * from './constants';
export * from './my-logistics.service';
export const MyLogistics: MyLogisticsInterface<MyLogisticsStatus> = {
url: 'https://api.mylogistics.com/v1',
apiKey: '',
apiSecret: '',
ignoreNotFound: false,
};
Error Handling
ErrorCode Reference
| Code | Constant | Usage |
|---|
| 999 | NOT_IMPLEMENTED | 未實現的功能 |
| 101 | NOT_FOUND_ERROR | 找不到追蹤號碼 |
| 102 | PERMISSION_DENIED | API 認證失敗 |
| 103 | INVALID_PARAMETER | 無效的參數 |
Best Practices
throw new LogisticsError(ErrorCode.NOT_FOUND_ERROR, 'Custom message');
if (this.configuration.ignoreNotFound) {
return { logisticsId: id, statusHistory: [] };
}
if (response.status === 403) {
throw new LogisticsError(ErrorCode.PERMISSION_DENIED);
}
Testing Guidelines
import { MyLogisticsService, MyLogistics } from '../src';
import { LogisticsError, ErrorCode } from '@rytass/logistics';
describe('MyLogisticsService', () => {
const service = new MyLogisticsService({
...MyLogistics,
apiKey: 'test-key',
apiSecret: 'test-secret',
});
it('should trace single package', async () => {
const result = await service.trace('TRACK-001');
expect(result).toHaveLength(1);
expect(result[0].logisticsId).toBe('TRACK-001');
});
it('should trace multiple packages', async () => {
const result = await service.trace(['TRACK-001', 'TRACK-002']);
expect(result).toHaveLength(2);
});
it('should handle not found with ignoreNotFound', async () => {
const serviceWithIgnore = new MyLogisticsService({
...MyLogistics,
ignoreNotFound: true,
});
const result = await serviceWithIgnore.trace('INVALID');
expect(result[0].statusHistory).toHaveLength(0);
});
});
Package Structure
my-logistics-adapter/
├── src/
│ ├── index.ts
│ ├── typings.ts
│ ├── constants.ts
│ └── my-logistics.service.ts
├── __tests__/
│ └── my-logistics.spec.ts
├── package.json
├── tsconfig.build.json
└── README.md
Publishing Checklist
