Vito API 与购买

Authorization: Bearer vito_live_xxxxxxxxxxxxxxxx

npm install @vetox-bot/vito

import { VitoClient } from '@vetox-bot/vito';

const vito = new VitoClient({ apiKey: process.env.VITO_API_KEY });

const project = await vito.auth.verify();

console.log(project.status);    // "active"
console.log(project.scopes);    // ["balance:read", "deduct:create", …]
console.log(project.rateLimit); // { tier, requestsPerMinute, requestsPerHour }

const wallet = await vito.balance.retrieve('123456789012345678');

if (!wallet.hasPin) {
  // 还没有设置钱包 PIN，因此无法批准任何扣款。
}

const confirmation = await vito.payments.deduct({
  discordId: '123456789012345678',
  guildId: '987654321098765432',
  amount: 250,
  reason: '传说之剑',
  merchantRef: 'order_10423',
  metadata: { sku: 'sword-legendary' },
  product: {
    type: 'virtual_item',
    name: '传说之剑',
    description: '造成 120 点伤害。',
    imageUrl: 'https://cdn.example.com/sword.png',
  },
});

console.log(confirmation.confirmUrl); // 把用户引导到这里
console.log(confirmation.expiresAt);  // unix 毫秒，10 分钟后

const credit = await vito.payments.credit(
  {
    discordId: '123456789012345678',
    amount: 250,
    reason: '订单 order_10423 退款',
    merchantRef: 'refund_10423',
  },
  // 用你自己的记录派生这个键，可让任务队列里的重跑变得安全：
  // 重复执行会返回原始结果，而不会第二次付款。
  { idempotencyKey: 'refund_10423' },
);

console.log(credit.transactionId, credit.ownerBalance, credit.recipientBalance);

const since = Date.now() - 24 * 60 * 60 * 1000;

// 一个按需拉取分页的异步生成器 — 无需手写翻页循环。
for await (const tx of vito.transactions.iterate({ limit: 100 })) {
  if (tx.date < since) break; // 最新的在前
  // tx.type 表示相对 tx.discordId 的方向：1 = 转入，0 = 转出。
}

await vito.payments.credit(params, { idempotencyKey: `refund_${orderId}` });

import { Webhooks, VitoSignatureVerificationError } from '@vetox-bot/vito';

try {
  const event = Webhooks.constructEvent({
    payload: rawRequestBody, // 原始请求体 — 见下方警告
    signature: req.header('x-vito-signature') ?? '',
    secret: process.env.VITO_WEBHOOK_SECRET,
  });

  if (event.eventType === 'confirmation.completed') {
    // data 字段的类型会根据 eventType 自动收窄。
    await fulfil(event.data.merchantRef);
  }
} catch (error) {
  if (error instanceof VitoSignatureVerificationError) {
    // 用 400 拒绝这次投递：伪造、过期，或请求体被重新序列化。
  }
}

export const runtime = 'nodejs'; // 校验使用 node:crypto

export async function POST(request: Request) {
  const event = await Webhooks.constructEventFromRequest(request, {
    secret: process.env.VITO_WEBHOOK_SECRET,
  });

  return Response.json({ received: true });
}

import { isVitoError, VitoInsufficientFundsError } from '@vetox-bot/vito';

try {
  await vito.payments.deduct(params);
} catch (error) {
  if (error instanceof VitoInsufficientFundsError) return notEnoughVito();

  if (isVitoError(error)) {
    logger.error({ code: error.code, requestId: error.requestId });
  }
  throw error;
}

const controller = new AbortController();
setTimeout(() => controller.abort(), 2000);

await vito.balance.retrieve(id, { signal: controller.signal });

X-Vito-Signature: ts=<unix>;h1=<hex>

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const parts = header.split(';');
  const ts = parts.find(p => p.startsWith('ts='))?.slice(3);
  const sigs = parts.filter(p => p.startsWith('h1=')).map(p => p.slice(3));
  if (!ts || sigs.length === 0) return false;

  // Reject anything older than ~5 minutes — replay protection.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = Buffer.from(
    crypto.createHmac('sha256', secret).update(`${ts}:${rawBody}`).digest('hex'),
  );

  // Any matching signature is valid — a rotation emits several.
  return sigs.some(sig => {
    const actual = Buffer.from(sig);
    // timingSafeEqual throws when the lengths differ, so check first.
    return (
      actual.length === expected.length && crypto.timingSafeEqual(actual, expected)
    );
  });
}

{
  "success": false,
  "error": {
    "type": "Forbidden",
    "message": "API key lacks the required scope for this operation.",
    "code": "VITO_INSUFFICIENT_SCOPE"
  },
  "requestId": "…",
  "timestamp": 1735161600000
}