@invonetwork/web-sdk 3.3.0 → 3.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/server.cjs CHANGED
@@ -250,6 +250,121 @@ var InvoError = class _InvoError extends Error {
250
250
  get isSteamPurchaseLayerRequired() {
251
251
  return this.code === "STEAM_PURCHASE_LAYER_REQUIRED";
252
252
  }
253
+ /**
254
+ * True if the title has no Steam application registered with INVO yet
255
+ * (`STEAM_NOT_CONFIGURED`, 503).
256
+ *
257
+ * Steam pays whoever owns the Steam app, so every INVO title bills through
258
+ * ITS OWN Steam application. The studio adds their Steam app id and publisher
259
+ * Web API key in the INVO dashboard; until then the rail is closed. Earlier
260
+ * SDK versions said purchases ran through an INVO-owned Steam app and there
261
+ * was nothing to register — that is no longer true.
262
+ *
263
+ * Not retryable; the fix is a setup step in the dashboard.
264
+ */
265
+ get isSteamNotConfigured() {
266
+ return this.code === "STEAM_NOT_CONFIGURED";
267
+ }
268
+ /**
269
+ * True if the order was started against a DIFFERENT Steam application than the
270
+ * title is configured for now (`STEAM_APP_CHANGED`, 409).
271
+ *
272
+ * Happens when a studio swaps their Steam app while orders are in flight. The
273
+ * in-flight order cannot be captured under the new app — contact INVO to
274
+ * settle it. New purchases work normally.
275
+ */
276
+ get isSteamAppChanged() {
277
+ return this.code === "STEAM_APP_CHANGED";
278
+ }
279
+ /**
280
+ * True if the studio has not finished INVO billing setup
281
+ * (`PARTNER_BILLING_NOT_SET_UP`, 409).
282
+ *
283
+ * On Steam, Valve pays the STUDIO and INVO issues the player's currency, so
284
+ * INVO settles with the studio afterwards against a payment method they keep
285
+ * on file. No payment method, no sale. Not retryable; it is a dashboard step.
286
+ */
287
+ get isPartnerBillingNotSetUp() {
288
+ return this.code === "PARTNER_BILLING_NOT_SET_UP";
289
+ }
290
+ /**
291
+ * True if the studio's settlement has been suspended (`PARTNER_RAIL_SUSPENDED`,
292
+ * 409) or they are temporarily over their settlement limit
293
+ * (`PARTNER_CREDIT_UNAVAILABLE`, 409).
294
+ *
295
+ * Refused BEFORE the player is charged, which is deliberate — the alternative
296
+ * is taking their money for currency that cannot be issued. Show a neutral
297
+ * "purchases are unavailable right now"; do not surface it as the player's
298
+ * problem, because it is not.
299
+ */
300
+ get isPartnerSettlementUnavailable() {
301
+ return this.code === "PARTNER_RAIL_SUSPENDED" || this.code === "PARTNER_CREDIT_UNAVAILABLE";
302
+ }
303
+ /** True when the studio's settlement float cannot cover this purchase right
304
+ * now (`PARTNER_CREDIT_UNAVAILABLE`, 409) — the structure (billing profile,
305
+ * mandate, payment method) is in place; the MONEY is not. Fixed by the
306
+ * studio topping up (or a settlement sweep clearing), not by the player.
307
+ * Show a plain failure ("try again later"); do NOT hot-poll init — headroom
308
+ * changes on a human action, and each retry briefly re-reserves headroom.
309
+ * A manual retry MUST reuse the same purchaseReference. */
310
+ get isPartnerCreditUnavailable() {
311
+ return this.code === "PARTNER_CREDIT_UNAVAILABLE";
312
+ }
313
+ /** True when the studio's settlement rail is suspended
314
+ * (`PARTNER_RAIL_SUSPENDED`, 409) — collections failed repeatedly or an
315
+ * admin intervened. Terminal from the game's seat: no retry can succeed
316
+ * until the studio resolves it in the INVO console. */
317
+ get isPartnerRailSuspended() {
318
+ return this.code === "PARTNER_RAIL_SUSPENDED";
319
+ }
320
+ /** True when init-purchase was given a `packId` that is not in INVO's Steam
321
+ * catalogue (`UNKNOWN_STEAM_PACK`, 400). The error body's
322
+ * `valid_pack_ids` lists what exists; re-fetch `steamPacks()` — the
323
+ * catalogue is INVO's and can change without a deploy on your side. */
324
+ get isUnknownSteamPack() {
325
+ return this.code === "UNKNOWN_STEAM_PACK";
326
+ }
327
+ /** True when a web-session init was sent without the player's IP
328
+ * (`MISSING_PLAYER_IP`, 400). Always an integration bug: `playerIp` is
329
+ * required for `usersession: "web"` and must be the PLAYER's address as
330
+ * your server sees it — never your server's own. */
331
+ get isMissingPlayerIp() {
332
+ return this.code === "MISSING_PLAYER_IP";
333
+ }
334
+ /** True when finalize was called before the player approved the charge
335
+ * (409, `status: "not_authorized"` with Steam still reporting `Init`, or
336
+ * no status yet). THE NORMAL WAIT STATE — keep polling / wait for the
337
+ * client callback and call finalize again. Contrast
338
+ * {@link isSteamAuthorizationDead}.
339
+ *
340
+ * PENDING IS THE CLOSED SET, deliberately. The first version of this pair
341
+ * enumerated the DEAD statuses and made pending the complement — so a
342
+ * player pressing Cancel in the overlay (the most common non-approval
343
+ * outcome, which Steam reports as a status the list did not name)
344
+ * classified as "keep polling forever": the exact failure these getters
345
+ * exist to prevent, reintroduced by enumerating the author's hazards
346
+ * instead of the backend's vocabulary. Only `Init` (and an absent status)
347
+ * can mean "not yet"; every named status that is not Init is an outcome. */
348
+ get isSteamAuthorizationPending() {
349
+ const b = this.body;
350
+ if (!b || b["status"] !== "not_authorized") return false;
351
+ const st = String(b["steam_status"] ?? "").toLowerCase();
352
+ return st === "init" || st === "";
353
+ }
354
+ /** True when finalize reports the Steam transaction TERMINALLY not-approved:
355
+ * `not_authorized` with any settled status — Failed, Cancelled, Refunded,
356
+ * Chargedback, and every other non-Init outcome. STOP polling: no later
357
+ * call can succeed. (Dead is the open set on purpose: an unrecognised new
358
+ * status stops a poller rather than trapping it, and stopping wrongly costs
359
+ * one support question while polling wrongly runs forever.) A finalize
360
+ * answering `"Order is not finalizable"` with no `not_authorized` status is
361
+ * equally terminal — the reconciler has already settled the order's fate. */
362
+ get isSteamAuthorizationDead() {
363
+ const b = this.body;
364
+ if (!b || b["status"] !== "not_authorized") return false;
365
+ const st = String(b["steam_status"] ?? "").toLowerCase();
366
+ return st !== "init" && st !== "";
367
+ }
253
368
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
254
369
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
255
370
  get isBelowCardMinimum() {
@@ -1220,7 +1335,7 @@ var InvoServer = class {
1220
1335
  }
1221
1336
  if (input.rail === "steam") {
1222
1337
  throw new InvoError({
1223
- message: 'rail "steam" is not a /purchase-currency flow \u2014 Steam uses the dedicated in-client Steam endpoints.',
1338
+ message: 'rail "steam" is not a /purchase-currency flow \u2014 use steamPacks() / steamInitPurchase() / steamFinalizePurchase().',
1224
1339
  code: "WRONG_RAIL_ENDPOINT",
1225
1340
  status: 0
1226
1341
  });
@@ -1291,6 +1406,150 @@ var InvoServer = class {
1291
1406
  );
1292
1407
  return toOrderDetails(raw);
1293
1408
  }
1409
+ /**
1410
+ * The Steam packs INVO sells, and what each contains for one player.
1411
+ *
1412
+ * The PRICE is identical for every player and is INVO's to set; the
1413
+ * `currencyAmount` varies by country. Render it verbatim — never compute
1414
+ * currency from the sticker price (VAT and the storefront's revenue share
1415
+ * come out of the sticker before currency is derived), and never cache one
1416
+ * answer for all players. Without `steamid` the quote assumes no VAT — the
1417
+ * most any pack yields; the purchase itself always re-derives.
1418
+ *
1419
+ * Refusals: `err.isSteamRailNotEntitled` (403). A missing Steam
1420
+ * registration does NOT refuse here — packs deliberately answers with the
1421
+ * no-VAT catalogue and lets the PURCHASE be what refuses; the only 503 is
1422
+ * the rail being disabled platform-wide, whose body carries no error code.
1423
+ */
1424
+ async steamPacks(query, opts) {
1425
+ const qs = query?.steamid ? `?steamid=${encodeURIComponent(query.steamid)}` : "";
1426
+ const raw = await this.http.get(
1427
+ `/api/currency-purchases/steam/packs${qs}`,
1428
+ this.auth,
1429
+ { signal: opts?.signal }
1430
+ );
1431
+ const packs = Array.isArray(raw["packs"]) ? raw["packs"] : [];
1432
+ return {
1433
+ packs: packs.map((p) => ({
1434
+ packId: String(p["pack_id"] ?? ""),
1435
+ label: String(p["label"] ?? ""),
1436
+ priceUsd: String(p["price_usd"] ?? ""),
1437
+ currencyAmount: String(p["currency_amount"] ?? "")
1438
+ })),
1439
+ country: raw["country"] ?? null,
1440
+ vatRatePct: String(raw["vat_rate_pct"] ?? "0"),
1441
+ raw
1442
+ };
1443
+ }
1444
+ /**
1445
+ * Start a Steam micro-transaction. The player then authorizes — in the Steam
1446
+ * overlay (`usersession: "client"`, the default) or on Steam's hosted
1447
+ * checkout page (`usersession: "web"`, returned as `steamCheckoutUrl`; open
1448
+ * it as a TOP-LEVEL tab, never an iframe; requires `playerIp`). After
1449
+ * authorization, call {@link steamFinalizePurchase} with the returned
1450
+ * `orderId`.
1451
+ *
1452
+ * Idempotent on `purchaseReference`, with one wire subtlety: a resend does
1453
+ * not replay the original body — it answers **409 `DUPLICATE_REQUEST`**
1454
+ * whose body carries the existing `order_id` (read it from `err.body`).
1455
+ * Never double-charges. Retries — including manual retries after a 409 —
1456
+ * MUST reuse the reference; a fresh one is a second intended purchase. For
1457
+ * WEB sessions, persist `steamCheckoutUrl` from the first success: the 409
1458
+ * body does not repeat it.
1459
+ *
1460
+ * Refusals worth branching on: `err.isPartnerCreditUnavailable` (409, the
1461
+ * studio's settlement float cannot cover it — plain failure toast, do NOT
1462
+ * hot-poll), `err.isPartnerRailSuspended` (409, terminal from the game's
1463
+ * seat), `err.isPartnerBillingNotSetUp` (409), `err.isUnknownSteamPack`
1464
+ * (400 — re-fetch `steamPacks()`), `err.isSteamNotConfigured` (503),
1465
+ * `err.isSteamRailNotEntitled` (403), `err.isMissingPlayerIp` (400),
1466
+ * `err.isDuplicateRequest` (409).
1467
+ */
1468
+ async steamInitPurchase(input, opts) {
1469
+ if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
1470
+ throw invalidInput("playerEmail", input.playerEmail, "is required");
1471
+ }
1472
+ if (!/^[0-9]+$/.test(String(input.steamid ?? ""))) {
1473
+ throw invalidInput("steamid", input.steamid, "must be the player's numeric 64-bit Steam id");
1474
+ }
1475
+ if (!input.packId) throw invalidInput("packId", input.packId, "is required \u2014 fetch steamPacks()");
1476
+ if (!input.purchaseReference) {
1477
+ throw new InvoError({
1478
+ message: "purchaseReference is required (idempotency key, unique per intended purchase).",
1479
+ code: "MISSING_PURCHASE_REFERENCE",
1480
+ status: 0
1481
+ });
1482
+ }
1483
+ if (input.usersession === "web" && !input.playerIp) {
1484
+ throw new InvoError({
1485
+ message: `playerIp is required when usersession is "web" \u2014 the PLAYER's IP, not your server's.`,
1486
+ code: "MISSING_PLAYER_IP",
1487
+ status: 0
1488
+ });
1489
+ }
1490
+ const body = {
1491
+ player_email: input.playerEmail,
1492
+ steamid: String(input.steamid),
1493
+ pack_id: input.packId,
1494
+ purchase_reference: input.purchaseReference
1495
+ };
1496
+ if (input.usersession) body["usersession"] = input.usersession;
1497
+ if (input.playerIp) body["player_ip"] = input.playerIp;
1498
+ if (input.playerName) body["player_name"] = input.playerName;
1499
+ if (input.metadata) body["metadata"] = input.metadata;
1500
+ const raw = await this.http.post(
1501
+ "/api/currency-purchases/steam/init-purchase",
1502
+ body,
1503
+ this.auth,
1504
+ { idempotent: true, signal: opts?.signal }
1505
+ // purchase_reference dedupes server-side
1506
+ );
1507
+ return {
1508
+ status: String(raw["status"] ?? ""),
1509
+ orderId: String(raw["order_id"] ?? ""),
1510
+ steamTransid: raw["steam_transid"],
1511
+ steamCheckoutUrl: raw["steam_checkout_url"] ?? void 0,
1512
+ packId: raw["pack_id"],
1513
+ chargedUsd: raw["charged_usd"],
1514
+ currencyAmount: raw["currency_amount"],
1515
+ raw
1516
+ };
1517
+ }
1518
+ /**
1519
+ * Capture an authorized Steam transaction and credit the player.
1520
+ *
1521
+ * Idempotent: a retry or duplicate returns `alreadyProcessed: true` and
1522
+ * never credits twice. Poller taxonomy — NOT every 409 means "not yet":
1523
+ *
1524
+ * - `err.isSteamAuthorizationPending` — the player has not approved yet
1525
+ * (Steam still reports Init). Wait / poll again. THE NORMAL STATE.
1526
+ * - `err.isSteamAuthorizationDead` — Failed / Refunded / Chargedback.
1527
+ * STOP polling; no later call can succeed.
1528
+ * - `err.isSteamAppChanged` (409) — the title's registration changed under
1529
+ * the order. Terminal for this order.
1530
+ * - 502 / 503 — transient; retry.
1531
+ *
1532
+ * A missed finalize is not a lost credit: INVO's reconciler independently
1533
+ * detects the authorized transaction and credits, on a delay.
1534
+ */
1535
+ async steamFinalizePurchase(input, opts) {
1536
+ if (!input.orderId) throw invalidInput("orderId", input.orderId, "is required (from steamInitPurchase)");
1537
+ const raw = await this.http.post(
1538
+ "/api/currency-purchases/steam/finalize-purchase",
1539
+ { order_id: input.orderId },
1540
+ this.auth,
1541
+ { idempotent: true, signal: opts?.signal }
1542
+ // backend replays a completed order
1543
+ );
1544
+ return {
1545
+ status: String(raw["status"] ?? ""),
1546
+ orderId: raw["order_id"] ?? void 0,
1547
+ transactionId: raw["transaction_id"] ?? void 0,
1548
+ newBalance: raw["new_balance"] ?? null,
1549
+ alreadyProcessed: raw["already_processed"] === true,
1550
+ raw
1551
+ };
1552
+ }
1294
1553
  /**
1295
1554
  * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
1296
1555
  * No real money, no payment rail, no passkey — it's a balance debit, authenticated
package/dist/server.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, b as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as PurchaseItemInput, N as PurchaseItemResult, Q as ItemHistoryQuery, T as ItemHistoryResult, U as ItemOrderQuery, W as PlayerBalanceQuery, X as PlayerBalanceResult, Y as InboundPendingQuery, Z as InboundPendingResult, _ as LinkedIdentitiesQuery, $ as LinkedIdentitiesResult, a0 as SmsVerifyResult, a1 as ClaimTransferInput, a2 as ClaimResult, a3 as ClaimCurrencyInput, a4 as TransactionStatusResult, a5 as GuardianApprovalStatusResult, a6 as ServerDestinationsQuery, d as DestinationsResult, a7 as PhoneShareContact, a8 as PhoneShareInitiateResult, a9 as PhoneShareApproveInput, aa as PhoneShareApproveResult, ab as PhoneShareStatusResult } from './types-DzmukUr9.cjs';
2
- export { ac as CurrencyBalance, h as DestinationGame, ad as FundingSource, ae as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, af as LinkedIdentityEmail, ag as PlatformPurchaseStatus, n as Rail, V as VerificationMethod } from './types-DzmukUr9.cjs';
1
+ import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, c as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as SteamPacksQuery, N as SteamPacksResult, Q as SteamInitPurchaseInput, T as SteamInitPurchaseResult, U as SteamFinalizeInput, W as SteamFinalizeResult, X as PurchaseItemInput, Y as PurchaseItemResult, Z as ItemHistoryQuery, _ as ItemHistoryResult, $ as ItemOrderQuery, a0 as PlayerBalanceQuery, a1 as PlayerBalanceResult, a2 as InboundPendingQuery, a3 as InboundPendingResult, a4 as LinkedIdentitiesQuery, a5 as LinkedIdentitiesResult, a6 as SmsVerifyResult, a7 as ClaimTransferInput, a8 as ClaimResult, a9 as ClaimCurrencyInput, aa as TransactionStatusResult, ab as GuardianApprovalStatusResult, ac as ServerDestinationsQuery, d as DestinationsResult, ad as PhoneShareContact, ae as PhoneShareInitiateResult, af as PhoneShareApproveInput, ag as PhoneShareApproveResult, ah as PhoneShareStatusResult } from './types-ZNoG09S5.cjs';
2
+ export { ai as CurrencyBalance, h as DestinationGame, aj as FundingSource, ak as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, al as LinkedIdentityEmail, am as PlatformPurchaseStatus, n as Rail, an as SteamPack, ao as SteamUserSession, V as VerificationMethod } from './types-ZNoG09S5.cjs';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -24,8 +24,16 @@ interface PurchaseCompletedData {
24
24
  currency_amount: string;
25
25
  currency_name: string;
26
26
  new_balance: string;
27
+ /** Which settlement rail carried the money. Provider-neutral. */
27
28
  rail: string;
28
- /** The metadata you passed to createCheckout/purchaseCurrency, echoed back (all rails). */
29
+ /**
30
+ * Which STOREFRONT the purchase came from — "steam" / "ios" / "android" /
31
+ * "web" / "console" — beside the rail it was paid on. Read off the order,
32
+ * not the request. `null` when the caller used a legacy game key: that is a
33
+ * real answer ("unattributed"), read it as one.
34
+ */
35
+ channel?: string | null;
36
+ /** The metadata you passed to createCheckout/purchaseCurrency/steamInitPurchase, echoed back (all rails). */
29
37
  metadata?: Record<string, unknown>;
30
38
  [key: string]: unknown;
31
39
  }
@@ -338,6 +346,65 @@ declare class InvoServer {
338
346
  orderId?: string;
339
347
  transactionId?: string;
340
348
  }, opts?: CallOptions): Promise<OrderDetailsResult>;
349
+ /**
350
+ * The Steam packs INVO sells, and what each contains for one player.
351
+ *
352
+ * The PRICE is identical for every player and is INVO's to set; the
353
+ * `currencyAmount` varies by country. Render it verbatim — never compute
354
+ * currency from the sticker price (VAT and the storefront's revenue share
355
+ * come out of the sticker before currency is derived), and never cache one
356
+ * answer for all players. Without `steamid` the quote assumes no VAT — the
357
+ * most any pack yields; the purchase itself always re-derives.
358
+ *
359
+ * Refusals: `err.isSteamRailNotEntitled` (403). A missing Steam
360
+ * registration does NOT refuse here — packs deliberately answers with the
361
+ * no-VAT catalogue and lets the PURCHASE be what refuses; the only 503 is
362
+ * the rail being disabled platform-wide, whose body carries no error code.
363
+ */
364
+ steamPacks(query?: SteamPacksQuery, opts?: CallOptions): Promise<SteamPacksResult>;
365
+ /**
366
+ * Start a Steam micro-transaction. The player then authorizes — in the Steam
367
+ * overlay (`usersession: "client"`, the default) or on Steam's hosted
368
+ * checkout page (`usersession: "web"`, returned as `steamCheckoutUrl`; open
369
+ * it as a TOP-LEVEL tab, never an iframe; requires `playerIp`). After
370
+ * authorization, call {@link steamFinalizePurchase} with the returned
371
+ * `orderId`.
372
+ *
373
+ * Idempotent on `purchaseReference`, with one wire subtlety: a resend does
374
+ * not replay the original body — it answers **409 `DUPLICATE_REQUEST`**
375
+ * whose body carries the existing `order_id` (read it from `err.body`).
376
+ * Never double-charges. Retries — including manual retries after a 409 —
377
+ * MUST reuse the reference; a fresh one is a second intended purchase. For
378
+ * WEB sessions, persist `steamCheckoutUrl` from the first success: the 409
379
+ * body does not repeat it.
380
+ *
381
+ * Refusals worth branching on: `err.isPartnerCreditUnavailable` (409, the
382
+ * studio's settlement float cannot cover it — plain failure toast, do NOT
383
+ * hot-poll), `err.isPartnerRailSuspended` (409, terminal from the game's
384
+ * seat), `err.isPartnerBillingNotSetUp` (409), `err.isUnknownSteamPack`
385
+ * (400 — re-fetch `steamPacks()`), `err.isSteamNotConfigured` (503),
386
+ * `err.isSteamRailNotEntitled` (403), `err.isMissingPlayerIp` (400),
387
+ * `err.isDuplicateRequest` (409).
388
+ */
389
+ steamInitPurchase(input: SteamInitPurchaseInput, opts?: CallOptions): Promise<SteamInitPurchaseResult>;
390
+ /**
391
+ * Capture an authorized Steam transaction and credit the player.
392
+ *
393
+ * Idempotent: a retry or duplicate returns `alreadyProcessed: true` and
394
+ * never credits twice. Poller taxonomy — NOT every 409 means "not yet":
395
+ *
396
+ * - `err.isSteamAuthorizationPending` — the player has not approved yet
397
+ * (Steam still reports Init). Wait / poll again. THE NORMAL STATE.
398
+ * - `err.isSteamAuthorizationDead` — Failed / Refunded / Chargedback.
399
+ * STOP polling; no later call can succeed.
400
+ * - `err.isSteamAppChanged` (409) — the title's registration changed under
401
+ * the order. Terminal for this order.
402
+ * - 502 / 503 — transient; retry.
403
+ *
404
+ * A missed finalize is not a lost credit: INVO's reconciler independently
405
+ * detects the authorized transaction and credits, on a delay.
406
+ */
407
+ steamFinalizePurchase(input: SteamFinalizeInput, opts?: CallOptions): Promise<SteamFinalizeResult>;
341
408
  /**
342
409
  * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
343
410
  * No real money, no payment rail, no passkey — it's a balance debit, authenticated
@@ -478,4 +545,4 @@ declare class InvoServer {
478
545
  private toInitiateResult;
479
546
  }
480
547
 
481
- export { CallOptions, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, DestinationsResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, ServerDestinationsQuery, SmsVerifyResult, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
548
+ export { CallOptions, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, DestinationsResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, ServerDestinationsQuery, SmsVerifyResult, SteamFinalizeInput, SteamFinalizeResult, SteamInitPurchaseInput, SteamInitPurchaseResult, SteamPacksQuery, SteamPacksResult, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
package/dist/server.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, b as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as PurchaseItemInput, N as PurchaseItemResult, Q as ItemHistoryQuery, T as ItemHistoryResult, U as ItemOrderQuery, W as PlayerBalanceQuery, X as PlayerBalanceResult, Y as InboundPendingQuery, Z as InboundPendingResult, _ as LinkedIdentitiesQuery, $ as LinkedIdentitiesResult, a0 as SmsVerifyResult, a1 as ClaimTransferInput, a2 as ClaimResult, a3 as ClaimCurrencyInput, a4 as TransactionStatusResult, a5 as GuardianApprovalStatusResult, a6 as ServerDestinationsQuery, d as DestinationsResult, a7 as PhoneShareContact, a8 as PhoneShareInitiateResult, a9 as PhoneShareApproveInput, aa as PhoneShareApproveResult, ab as PhoneShareStatusResult } from './types-DzmukUr9.js';
2
- export { ac as CurrencyBalance, h as DestinationGame, ad as FundingSource, ae as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, af as LinkedIdentityEmail, ag as PlatformPurchaseStatus, n as Rail, V as VerificationMethod } from './types-DzmukUr9.js';
1
+ import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, c as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as SteamPacksQuery, N as SteamPacksResult, Q as SteamInitPurchaseInput, T as SteamInitPurchaseResult, U as SteamFinalizeInput, W as SteamFinalizeResult, X as PurchaseItemInput, Y as PurchaseItemResult, Z as ItemHistoryQuery, _ as ItemHistoryResult, $ as ItemOrderQuery, a0 as PlayerBalanceQuery, a1 as PlayerBalanceResult, a2 as InboundPendingQuery, a3 as InboundPendingResult, a4 as LinkedIdentitiesQuery, a5 as LinkedIdentitiesResult, a6 as SmsVerifyResult, a7 as ClaimTransferInput, a8 as ClaimResult, a9 as ClaimCurrencyInput, aa as TransactionStatusResult, ab as GuardianApprovalStatusResult, ac as ServerDestinationsQuery, d as DestinationsResult, ad as PhoneShareContact, ae as PhoneShareInitiateResult, af as PhoneShareApproveInput, ag as PhoneShareApproveResult, ah as PhoneShareStatusResult } from './types-ZNoG09S5.js';
2
+ export { ai as CurrencyBalance, h as DestinationGame, aj as FundingSource, ak as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, al as LinkedIdentityEmail, am as PlatformPurchaseStatus, n as Rail, an as SteamPack, ao as SteamUserSession, V as VerificationMethod } from './types-ZNoG09S5.js';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -24,8 +24,16 @@ interface PurchaseCompletedData {
24
24
  currency_amount: string;
25
25
  currency_name: string;
26
26
  new_balance: string;
27
+ /** Which settlement rail carried the money. Provider-neutral. */
27
28
  rail: string;
28
- /** The metadata you passed to createCheckout/purchaseCurrency, echoed back (all rails). */
29
+ /**
30
+ * Which STOREFRONT the purchase came from — "steam" / "ios" / "android" /
31
+ * "web" / "console" — beside the rail it was paid on. Read off the order,
32
+ * not the request. `null` when the caller used a legacy game key: that is a
33
+ * real answer ("unattributed"), read it as one.
34
+ */
35
+ channel?: string | null;
36
+ /** The metadata you passed to createCheckout/purchaseCurrency/steamInitPurchase, echoed back (all rails). */
29
37
  metadata?: Record<string, unknown>;
30
38
  [key: string]: unknown;
31
39
  }
@@ -338,6 +346,65 @@ declare class InvoServer {
338
346
  orderId?: string;
339
347
  transactionId?: string;
340
348
  }, opts?: CallOptions): Promise<OrderDetailsResult>;
349
+ /**
350
+ * The Steam packs INVO sells, and what each contains for one player.
351
+ *
352
+ * The PRICE is identical for every player and is INVO's to set; the
353
+ * `currencyAmount` varies by country. Render it verbatim — never compute
354
+ * currency from the sticker price (VAT and the storefront's revenue share
355
+ * come out of the sticker before currency is derived), and never cache one
356
+ * answer for all players. Without `steamid` the quote assumes no VAT — the
357
+ * most any pack yields; the purchase itself always re-derives.
358
+ *
359
+ * Refusals: `err.isSteamRailNotEntitled` (403). A missing Steam
360
+ * registration does NOT refuse here — packs deliberately answers with the
361
+ * no-VAT catalogue and lets the PURCHASE be what refuses; the only 503 is
362
+ * the rail being disabled platform-wide, whose body carries no error code.
363
+ */
364
+ steamPacks(query?: SteamPacksQuery, opts?: CallOptions): Promise<SteamPacksResult>;
365
+ /**
366
+ * Start a Steam micro-transaction. The player then authorizes — in the Steam
367
+ * overlay (`usersession: "client"`, the default) or on Steam's hosted
368
+ * checkout page (`usersession: "web"`, returned as `steamCheckoutUrl`; open
369
+ * it as a TOP-LEVEL tab, never an iframe; requires `playerIp`). After
370
+ * authorization, call {@link steamFinalizePurchase} with the returned
371
+ * `orderId`.
372
+ *
373
+ * Idempotent on `purchaseReference`, with one wire subtlety: a resend does
374
+ * not replay the original body — it answers **409 `DUPLICATE_REQUEST`**
375
+ * whose body carries the existing `order_id` (read it from `err.body`).
376
+ * Never double-charges. Retries — including manual retries after a 409 —
377
+ * MUST reuse the reference; a fresh one is a second intended purchase. For
378
+ * WEB sessions, persist `steamCheckoutUrl` from the first success: the 409
379
+ * body does not repeat it.
380
+ *
381
+ * Refusals worth branching on: `err.isPartnerCreditUnavailable` (409, the
382
+ * studio's settlement float cannot cover it — plain failure toast, do NOT
383
+ * hot-poll), `err.isPartnerRailSuspended` (409, terminal from the game's
384
+ * seat), `err.isPartnerBillingNotSetUp` (409), `err.isUnknownSteamPack`
385
+ * (400 — re-fetch `steamPacks()`), `err.isSteamNotConfigured` (503),
386
+ * `err.isSteamRailNotEntitled` (403), `err.isMissingPlayerIp` (400),
387
+ * `err.isDuplicateRequest` (409).
388
+ */
389
+ steamInitPurchase(input: SteamInitPurchaseInput, opts?: CallOptions): Promise<SteamInitPurchaseResult>;
390
+ /**
391
+ * Capture an authorized Steam transaction and credit the player.
392
+ *
393
+ * Idempotent: a retry or duplicate returns `alreadyProcessed: true` and
394
+ * never credits twice. Poller taxonomy — NOT every 409 means "not yet":
395
+ *
396
+ * - `err.isSteamAuthorizationPending` — the player has not approved yet
397
+ * (Steam still reports Init). Wait / poll again. THE NORMAL STATE.
398
+ * - `err.isSteamAuthorizationDead` — Failed / Refunded / Chargedback.
399
+ * STOP polling; no later call can succeed.
400
+ * - `err.isSteamAppChanged` (409) — the title's registration changed under
401
+ * the order. Terminal for this order.
402
+ * - 502 / 503 — transient; retry.
403
+ *
404
+ * A missed finalize is not a lost credit: INVO's reconciler independently
405
+ * detects the authorized transaction and credits, on a delay.
406
+ */
407
+ steamFinalizePurchase(input: SteamFinalizeInput, opts?: CallOptions): Promise<SteamFinalizeResult>;
341
408
  /**
342
409
  * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
343
410
  * No real money, no payment rail, no passkey — it's a balance debit, authenticated
@@ -478,4 +545,4 @@ declare class InvoServer {
478
545
  private toInitiateResult;
479
546
  }
480
547
 
481
- export { CallOptions, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, DestinationsResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, ServerDestinationsQuery, SmsVerifyResult, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
548
+ export { CallOptions, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, DestinationsResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, ServerDestinationsQuery, SmsVerifyResult, SteamFinalizeInput, SteamFinalizeResult, SteamInitPurchaseInput, SteamInitPurchaseResult, SteamPacksQuery, SteamPacksResult, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
package/dist/server.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-ZLPMCR5Q.js';
2
- export { InvoError } from './chunk-ZLPMCR5Q.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-MBKE6ULW.js';
2
+ export { InvoError } from './chunk-MBKE6ULW.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  var DEFAULT_TOLERANCE_SEC = 300;
@@ -676,7 +676,7 @@ var InvoServer = class {
676
676
  }
677
677
  if (input.rail === "steam") {
678
678
  throw new InvoError({
679
- message: 'rail "steam" is not a /purchase-currency flow \u2014 Steam uses the dedicated in-client Steam endpoints.',
679
+ message: 'rail "steam" is not a /purchase-currency flow \u2014 use steamPacks() / steamInitPurchase() / steamFinalizePurchase().',
680
680
  code: "WRONG_RAIL_ENDPOINT",
681
681
  status: 0
682
682
  });
@@ -747,6 +747,150 @@ var InvoServer = class {
747
747
  );
748
748
  return toOrderDetails(raw);
749
749
  }
750
+ /**
751
+ * The Steam packs INVO sells, and what each contains for one player.
752
+ *
753
+ * The PRICE is identical for every player and is INVO's to set; the
754
+ * `currencyAmount` varies by country. Render it verbatim — never compute
755
+ * currency from the sticker price (VAT and the storefront's revenue share
756
+ * come out of the sticker before currency is derived), and never cache one
757
+ * answer for all players. Without `steamid` the quote assumes no VAT — the
758
+ * most any pack yields; the purchase itself always re-derives.
759
+ *
760
+ * Refusals: `err.isSteamRailNotEntitled` (403). A missing Steam
761
+ * registration does NOT refuse here — packs deliberately answers with the
762
+ * no-VAT catalogue and lets the PURCHASE be what refuses; the only 503 is
763
+ * the rail being disabled platform-wide, whose body carries no error code.
764
+ */
765
+ async steamPacks(query, opts) {
766
+ const qs = query?.steamid ? `?steamid=${encodeURIComponent(query.steamid)}` : "";
767
+ const raw = await this.http.get(
768
+ `/api/currency-purchases/steam/packs${qs}`,
769
+ this.auth,
770
+ { signal: opts?.signal }
771
+ );
772
+ const packs = Array.isArray(raw["packs"]) ? raw["packs"] : [];
773
+ return {
774
+ packs: packs.map((p) => ({
775
+ packId: String(p["pack_id"] ?? ""),
776
+ label: String(p["label"] ?? ""),
777
+ priceUsd: String(p["price_usd"] ?? ""),
778
+ currencyAmount: String(p["currency_amount"] ?? "")
779
+ })),
780
+ country: raw["country"] ?? null,
781
+ vatRatePct: String(raw["vat_rate_pct"] ?? "0"),
782
+ raw
783
+ };
784
+ }
785
+ /**
786
+ * Start a Steam micro-transaction. The player then authorizes — in the Steam
787
+ * overlay (`usersession: "client"`, the default) or on Steam's hosted
788
+ * checkout page (`usersession: "web"`, returned as `steamCheckoutUrl`; open
789
+ * it as a TOP-LEVEL tab, never an iframe; requires `playerIp`). After
790
+ * authorization, call {@link steamFinalizePurchase} with the returned
791
+ * `orderId`.
792
+ *
793
+ * Idempotent on `purchaseReference`, with one wire subtlety: a resend does
794
+ * not replay the original body — it answers **409 `DUPLICATE_REQUEST`**
795
+ * whose body carries the existing `order_id` (read it from `err.body`).
796
+ * Never double-charges. Retries — including manual retries after a 409 —
797
+ * MUST reuse the reference; a fresh one is a second intended purchase. For
798
+ * WEB sessions, persist `steamCheckoutUrl` from the first success: the 409
799
+ * body does not repeat it.
800
+ *
801
+ * Refusals worth branching on: `err.isPartnerCreditUnavailable` (409, the
802
+ * studio's settlement float cannot cover it — plain failure toast, do NOT
803
+ * hot-poll), `err.isPartnerRailSuspended` (409, terminal from the game's
804
+ * seat), `err.isPartnerBillingNotSetUp` (409), `err.isUnknownSteamPack`
805
+ * (400 — re-fetch `steamPacks()`), `err.isSteamNotConfigured` (503),
806
+ * `err.isSteamRailNotEntitled` (403), `err.isMissingPlayerIp` (400),
807
+ * `err.isDuplicateRequest` (409).
808
+ */
809
+ async steamInitPurchase(input, opts) {
810
+ if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
811
+ throw invalidInput("playerEmail", input.playerEmail, "is required");
812
+ }
813
+ if (!/^[0-9]+$/.test(String(input.steamid ?? ""))) {
814
+ throw invalidInput("steamid", input.steamid, "must be the player's numeric 64-bit Steam id");
815
+ }
816
+ if (!input.packId) throw invalidInput("packId", input.packId, "is required \u2014 fetch steamPacks()");
817
+ if (!input.purchaseReference) {
818
+ throw new InvoError({
819
+ message: "purchaseReference is required (idempotency key, unique per intended purchase).",
820
+ code: "MISSING_PURCHASE_REFERENCE",
821
+ status: 0
822
+ });
823
+ }
824
+ if (input.usersession === "web" && !input.playerIp) {
825
+ throw new InvoError({
826
+ message: `playerIp is required when usersession is "web" \u2014 the PLAYER's IP, not your server's.`,
827
+ code: "MISSING_PLAYER_IP",
828
+ status: 0
829
+ });
830
+ }
831
+ const body = {
832
+ player_email: input.playerEmail,
833
+ steamid: String(input.steamid),
834
+ pack_id: input.packId,
835
+ purchase_reference: input.purchaseReference
836
+ };
837
+ if (input.usersession) body["usersession"] = input.usersession;
838
+ if (input.playerIp) body["player_ip"] = input.playerIp;
839
+ if (input.playerName) body["player_name"] = input.playerName;
840
+ if (input.metadata) body["metadata"] = input.metadata;
841
+ const raw = await this.http.post(
842
+ "/api/currency-purchases/steam/init-purchase",
843
+ body,
844
+ this.auth,
845
+ { idempotent: true, signal: opts?.signal }
846
+ // purchase_reference dedupes server-side
847
+ );
848
+ return {
849
+ status: String(raw["status"] ?? ""),
850
+ orderId: String(raw["order_id"] ?? ""),
851
+ steamTransid: raw["steam_transid"],
852
+ steamCheckoutUrl: raw["steam_checkout_url"] ?? void 0,
853
+ packId: raw["pack_id"],
854
+ chargedUsd: raw["charged_usd"],
855
+ currencyAmount: raw["currency_amount"],
856
+ raw
857
+ };
858
+ }
859
+ /**
860
+ * Capture an authorized Steam transaction and credit the player.
861
+ *
862
+ * Idempotent: a retry or duplicate returns `alreadyProcessed: true` and
863
+ * never credits twice. Poller taxonomy — NOT every 409 means "not yet":
864
+ *
865
+ * - `err.isSteamAuthorizationPending` — the player has not approved yet
866
+ * (Steam still reports Init). Wait / poll again. THE NORMAL STATE.
867
+ * - `err.isSteamAuthorizationDead` — Failed / Refunded / Chargedback.
868
+ * STOP polling; no later call can succeed.
869
+ * - `err.isSteamAppChanged` (409) — the title's registration changed under
870
+ * the order. Terminal for this order.
871
+ * - 502 / 503 — transient; retry.
872
+ *
873
+ * A missed finalize is not a lost credit: INVO's reconciler independently
874
+ * detects the authorized transaction and credits, on a delay.
875
+ */
876
+ async steamFinalizePurchase(input, opts) {
877
+ if (!input.orderId) throw invalidInput("orderId", input.orderId, "is required (from steamInitPurchase)");
878
+ const raw = await this.http.post(
879
+ "/api/currency-purchases/steam/finalize-purchase",
880
+ { order_id: input.orderId },
881
+ this.auth,
882
+ { idempotent: true, signal: opts?.signal }
883
+ // backend replays a completed order
884
+ );
885
+ return {
886
+ status: String(raw["status"] ?? ""),
887
+ orderId: raw["order_id"] ?? void 0,
888
+ transactionId: raw["transaction_id"] ?? void 0,
889
+ newBalance: raw["new_balance"] ?? null,
890
+ alreadyProcessed: raw["already_processed"] === true,
891
+ raw
892
+ };
893
+ }
750
894
  /**
751
895
  * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
752
896
  * No real money, no payment rail, no passkey — it's a balance debit, authenticated