@openlee/virtual-parcel-admin

数字包裹系统管理端 SDK，用于运营者后台管理包裹。

安装

npm install @openlee/virtual-parcel-admin

快速开始

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

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

// 创建包裹
const code = await admin.createParcel({
  mode: 'perish',
  payload: {
    links: ['https://example.com/vip'],
    text: 'VIP access granted'
  }
});

console.log('生成的取件码：', code); // 例如：ABCD-X7K9

API 文档

创建包裹

const code = await admin.createParcel({
  mode: 'perish',  // 'perish' | 'reuse' | 'timed'
  payload: {
    links: ['https://example.com'],
    images: ['https://example.com/image.jpg'],
    videos: ['https://example.com/video.mp4'],
    text: 'Some text content',
    custom: { key: 'value' }
  },
  metadata: {
    price: 9.9,
    description: 'VIP access'
  },
  maxReuse: 10,  // reuse 模式
  expiresAt: new Date('2026-12-31')  // ttl 模式
});

批量创建

const codes = await admin.batchCreateParcels({
  count: 100,
  mode: 'reuse',
  maxReuse: 5,
  payload: {
    text: 'VIP access'
  }
});

console.log('生成的取件码：', codes); // ['ABCD-X7K9', 'EFGH-Y8L0', ...]

获取包裹详情

const parcel = await admin.getParcel('ABCD-X7K9');

if (parcel) {
  console.log('模式：', parcel.mode);
  console.log('使用次数：', parcel.usedCount);
  console.log('内容：', parcel.payload);
}

获取包裹列表

const parcels = await admin.listParcels({
  mode: 'perish',
  revoked: false,
  limit: 50,
  offset: 0
});

parcels.forEach(parcel => {
  console.log(parcel.code, parcel.mode, parcel.usedCount);
});

撤销包裹

const success = await admin.revokeParcel('ABCD-X7K9');

if (success) {
  console.log('撤销成功');
}

获取统计数据

const stats = await admin.getStats({
  startDate: new Date('2026-01-01'),
  endDate: new Date('2026-12-31')
});

console.log('总包裹数：', stats.total);
console.log('有效包裹：', stats.active);
console.log('已使用：', stats.consumed);
console.log('已过期：', stats.expired);
console.log('已撤销：', stats.revoked);

查看包裹（不消耗）

const result = await admin.peekParcel('ABCD-X7K9');

console.log('是否有效：', result.valid);
console.log('包裹信息：', result.parcel);

安全警告

⚠️ 重要：Admin SDK 拥有完整的包裹管理权限，绝对不能暴露在前端代码中！

正确的使用方式

// ✅ 正确：在 Node.js 后端使用
// server.js
app.post('/api/create-parcel', async (req, res) => {
  const admin = new VirtualParcelAdmin({
    backendUrl: 'https://api.virtual-parcel.com'
  });
  
  const code = await admin.createParcel(req.body);
  res.json({ code });
});

// ❌ 错误：在前端使用
// app.js - 不要这样做！
const admin = new VirtualParcelAdmin({
  backendUrl: 'https://api.virtual-parcel.com'
});

License

MIT