@openlee/virtual-parcel

数字包裹系统核心 SDK，提供取件码生成、验证、管理等功能。

安装

npm install @openlee/virtual-parcel

快速开始

基本用法

import { VirtualParcelSDK } from '@openlee/virtual-parcel';

// 初始化 SDK（使用远程后端）
const sdk = new VirtualParcelSDK({
  backendUrl: 'https://api.virtual-parcel.com'
});

// 验证取件码
const result = await sdk.verifyCode('ABCD-X7K9');

if (result.valid) {
  console.log('验证成功！');
  console.log('包裹内容：', result.parcel?.payload);
} else {
  console.error('验证失败：', result.message);
}

核销模式

1. 即焚模式 (perish)

取件码只能使用一次，使用后立即失效。

const code = await sdk.createParcel({
  mode: 'perish',
  payload: {
    links: ['https://example.com/vip']
  }
});

// 第一次验证：成功
await sdk.verifyCode(code);

// 第二次验证：失败（已使用）
await sdk.verifyCode(code);

2. 复用模式 (reuse)

取件码可以多次使用，可设置最大使用次数。

const code = await sdk.createParcel({
  mode: 'reuse',
  maxReuse: 10, // 最多使用 10 次
  payload: {
    text: '会员权益'
  }
});

const result = await sdk.verifyCode(code);
console.log(result.remainingUses); // 9

3. 时效模式 (timed)

取件码在指定时间内有效，可多次使用。

const code = await sdk.createParcel({
  mode: 'timed',
  expiresAt: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 天后过期
  payload: {
    videos: ['https://example.com/video.mp4']
  }
});

事件监听

sdk.on('verified', ({ code, parcel }) => {
  console.log(`取件码 ${code} 验证成功`);
});

sdk.on('expired', ({ code }) => {
  console.log(`取件码 ${code} 已过期`);
});

sdk.on('revoked', ({ code }) => {
  console.log(`取件码 ${code} 已被撤销`);
});

存储适配器

使用远程后端（推荐）

const sdk = new VirtualParcelSDK({
  backendUrl: 'https://api.virtual-parcel.com'
});

使用 localStorage（浏览器）

import { LocalStorageAdapter } from '@openlee/virtual-parcel';

const sdk = new VirtualParcelSDK({
  adapter: new LocalStorageAdapter()
});

使用内存存储（测试/演示）

import { MemoryAdapter } from '@openlee/virtual-parcel';

const sdk = new VirtualParcelSDK({
  adapter: new MemoryAdapter()
});

API 参考

VirtualParcelSDK

构造函数

new VirtualParcelSDK(config: SDKConfig)

方法

• verifyCode(code: string): Promise<VerifyResult> - 验证取件码
• getParcel(code: string): Promise<Parcel | null> - 获取包裹信息
• createParcel(input: CreateParcelInput): Promise<string> - 创建包裹
• revokeCode(code: string): Promise<boolean> - 撤销取件码
• on(event: string, callback: Function): void - 监听事件
• off(event: string, callback: Function): void - 取消监听

类型定义

ParcelMode

type ParcelMode = 'perish' | 'reuse' | 'timed';

Parcel

interface Parcel {
  id: string;
  code: string;
  mode: ParcelMode;
  createdAt: number;
  expiresAt?: number;
  maxReuse?: number;
  usedCount: number;
  payload: ParcelPayload;
  metadata?: Record<string, unknown>;
  consumedAt?: number;
  revoked: boolean;
}

VerifyResult

interface VerifyResult {
  valid: boolean;
  code: string;
  mode: ParcelMode;
  parcel?: Parcel;
  remainingUses?: number;
  expiresAt?: number;
  message?: string;
}

取件码格式

• 格式：XXXX-XXXX（8 个字符，分为两组）
• 字符集：23456789ABCDEFGHJKLMNPQRSTUVWXYZ（去除易混淆字符 0, 1, I, L, O）
• 容量：约 11 亿种组合

工具函数

import { generateCode, isValidCodeFormat, formatCode } from '@openlee/virtual-parcel';

// 生成取件码
const code = generateCode(); // "ABCD-X7K9"

// 验证格式
isValidCodeFormat('ABCD-X7K9'); // true
isValidCodeFormat('invalid'); // false

// 格式化
formatCode('ABCDX7K9'); // "ABCD-X7K9"

License

MIT