Web / TypeScript SDK

npm install @invonetwork/web-sdk

import { InvoServer, baseUrlForKey, environmentFromKeyPrefix } from "@invonetwork/web-sdk/server";

const gameSecret = process.env.INVO_GAME_SECRET!;
environmentFromKeyPrefix(gameSecret);         // "production" | "sandbox" | null

// Going live is swapping the key: the base URL follows it.
const invo = new InvoServer({ gameSecret, baseUrl: await baseUrlForKey(gameSecret) });

import { InvoServer } from "@invonetwork/web-sdk/server";

const invo = new InvoServer({
  gameSecret: process.env.INVO_GAME_SECRET!,          // server-side ONLY
  baseUrl: "https://sandbox.invo.network/sandbox",    // prod: https://invo.network
});

// Hand this short-lived (~15 min), game-scoped token to the browser.
const { token } = await invo.mintPlayerToken({ playerEmail: "p@example.com", playerPhone: "+15555550111" });

import { InvoClient } from "@invonetwork/web-sdk";

const invo = new InvoClient({
  token,                                              // fetched from your backend
  baseUrl: "https://sandbox.invo.network/sandbox",
  // Optional: auto re-mint + retry once if the token expires mid-session.
  refreshToken: () => fetch("/invo/token", { method: "POST" }).then(r => r.json()).then(j => j.token),
});

await invo.enrollPasskey();                           // once per user
await invo.approveSend(transactionId);                // or approveTransfer(...)

const { checkoutUrl, sessionId } = await invo.createCheckout({
  playerEmail: "p@example.com",
  usdAmount: "20.00",                  // USD, above 0 and within the current card limits
  rail: "platform",                    // optional: "platform" | "game" | "steam"
  metadata: { yourOrderId: "ord_42" }, // echoed on the purchase.completed webhook (all rails)
});
// → send the browser to checkoutUrl (single-use, ~15 min)

const { packs } = await invo.steamPacks({ steamid });   // priced for THIS player

const init = await invo.steamInitPurchase({
  playerEmail: "p@example.com",
  steamid,
  packId: packs[0].packId,               // never a price
  purchaseReference: myIdempotencyKey,   // reuse on every retry
  metadata: { playerId: myPlayerId },    // echoed on purchase.completed
  // usersession: "web", playerIp,       // browser checkout -> init.steamCheckoutUrl
});

// after the player approves (overlay callback / checkout page):
const done = await invo.steamFinalizePurchase({ orderId: init.orderId });
// done.newBalance; a replay returns alreadyProcessed: true, never a double credit

const item = await invo.purchaseItem({
  clientRequestId: crypto.randomUUID(),  // idempotency key, unique per game
  playerEmail: "p@example.com",
  playerName: "P",
  itemId: "sword_001",
  itemName: "Legendary Sword",
  itemQuantity: 1,                       // integer 1..1000
  unitPrice: "100.00",                   // > 0 and ≤ 999999.99
  totalPrice: "100.00",                  // must equal unitPrice × itemQuantity (±0.01)
});
// item.status === "success", item.newBalance, item.transactionId, item.orderId

const { balances, summary } = await invo.getPlayerBalance({ playerEmail: "p@example.com" });
// balances: [{ currencyName, availableBalance, reservedBalance, totalBalance }] (currencySymbol is always "": the API returns no symbol)
// by email only: there is no by-id balance route, and passing playerId throws INVALID_INPUT.
// In the browser, read the player's own balance with InvoClient.getBalance() (player token).

// SERVER: initiate, then branch on how the sender must verify
const t = await invo.initiateTransfer({
  clientRequestId: crypto.randomUUID(),
  sourcePlayerName: "P", sourcePlayerEmail: "p@example.com", sourcePlayerPhone: "+15555550100",
  targetPlayerEmail: "q@example.com", targetPlayerPhone: "+15555550111",
  targetGameId: 123456, amount: "50",
});
// t.verificationMethod: "in_app" | "sms" (legacy value; approve with a passkey either way) | undefined (guardian, HTTP 202)

// BROWSER: sender approves; recipient self-claims (fall back to claim code if not enrolled)
const approved = await invo.approveTransfer(t.transactionId);   // returns claimCode
await invo.confirmReceiptTransfer(t.transactionId);             // or use approved.claimCode

await invo.enrollPasskey();              // once per user

// Interchangeable methods: prove an existing method (e.g. the Invo app device key,
// or a passkey on your own domain) to authorize adding this one, then enroll.
// No arguments from 3.10.1 on: the server mints the link id.
await invo.linkDevice();                 // → { status: "authorized" }
await invo.enrollPasskey();

// First-enrollment OTP grant (v0.6.0+): some tenants require it:
try {
  await invo.enrollPasskey();
} catch (e) {
  if (e.isEnrollmentAuthorizationRequired) {      // 6-digit code to phone + email
    await invo.enrollmentBegin();
    await invo.enrollmentVerify(codeFromUser);
    await invo.enrollPasskey();                    // retry; grant auto-consumed
  } else if (e.isEnrollmentProofRequired) {      // they still HAVE a method: link, don't recover
    await invo.linkDevice(); await invo.enrollPasskey();
  } else throw e;
}

import { verifyWebhook, InvoError } from "@invonetwork/web-sdk/server";

// Pass the RAW request bytes + the X-Invo-Signature header.
let event;
try {
  event = verifyWebhook(rawBody, signatureHeader, process.env.INVO_WEBHOOK_SECRET);
} catch (e) {
  return respond(400); // InvoError: WEBHOOK_SIGNATURE_INVALID | WEBHOOK_TIMESTAMP_EXPIRED | WEBHOOK_MALFORMED
}
// De-dupe yourself on X-Invo-Idempotency-Key, then handle:
switch (event.event_type) {
  case "purchase.completed":
    // a paid card subscription renewal also sends this for the coins it minted: grant NOTHING on it
    if (event.data.metadata?.source === "subscription_renewal") break;   // use subscription.renewed
    grantCurrency(event.data); break;                                     // event.data is typed
  case "item.purchased":     grantItem(event.data);     break;
}

const invo = new InvoServer({
  gameSecret: process.env.INVO_GAME_SECRET,
  baseUrl: "https://sandbox.invo.network/sandbox",
  maxRetries: 2,                 // default; 0 disables
  hooks: {
    onResponse: ({ status, durationMs, requestId }) => metrics(status, durationMs),
    onError:    ({ error, willRetry }) => log(error.code, error.requestId, willRetry),
  },
});