API Vito e acquisti

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) {
  // Non ha ancora un PIN del portafoglio, quindi non può confermare alcun addebito.
}

const confirmation = await vito.payments.deduct({
  discordId: '123456789012345678',
  guildId: '987654321098765432',
  amount: 250,
  reason: 'Spada leggendaria',
  merchantRef: 'order_10423',
  metadata: { sku: 'sword-legendary' },
  product: {
    type: 'virtual_item',
    name: 'Spada leggendaria',
    description: 'Infligge 120 danni.',
    imageUrl: 'https://cdn.example.com/sword.png',
  },
});

console.log(confirmation.confirmUrl); // manda qui l'utente
console.log(confirmation.expiresAt);  // unix ms, fra 10 minuti

const credit = await vito.payments.credit(
  {
    discordId: '123456789012345678',
    amount: 250,
    reason: 'Rimborso ordine order_10423',
    merchantRef: 'refund_10423',
  },
  // Derivare la chiave dal tuo archivio rende sicuro rilanciare l'operazione da
  // una coda di lavori: una ripetizione restituisce il risultato originale invece
  // di pagare due volte.
  { idempotencyKey: 'refund_10423' },
);

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

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

// Un generatore asincrono che carica le pagine su richiesta — nessun ciclo manuale.
for await (const tx of vito.transactions.iterate({ limit: 100 })) {
  if (tx.date < since) break; // le più recenti per prime
  // tx.type è la direzione rispetto a tx.discordId: 1 = in entrata, 0 = in uscita.
}

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

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

try {
  const event = Webhooks.constructEvent({
    payload: rawRequestBody, // il corpo grezzo — vedi l'avviso qui sotto
    signature: req.header('x-vito-signature') ?? '',
    secret: process.env.VITO_WEBHOOK_SECRET,
  });

  if (event.eventType === 'confirmation.completed') {
    // Il tipo di data si restringe automaticamente in base a eventType.
    await fulfil(event.data.merchantRef);
  }
} catch (error) {
  if (error instanceof VitoSignatureVerificationError) {
    // Rifiuta la consegna con un 400: falsificata, scaduta o corpo riserializzato.
  }
}

export const runtime = 'nodejs'; // la verifica usa 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
}