@invonetwork/web-sdk 3.2.3 → 3.5.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/CHANGELOG.md +97 -0
- package/README.md +158 -34
- package/dist/{chunk-ZLPMCR5Q.js → chunk-MBKE6ULW.js} +117 -2
- package/dist/index.cjs +115 -0
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/server.cjs +260 -1
- package/dist/server.d.cts +71 -4
- package/dist/server.d.ts +71 -4
- package/dist/server.js +147 -3
- package/dist/{types-DzmukUr9.d.cts → types-Dxo3IsYq.d.cts} +197 -1
- package/dist/{types-DzmukUr9.d.ts → types-Dxo3IsYq.d.ts} +197 -1
- package/package.json +1 -1
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
|
|
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
|
|
2
|
-
export {
|
|
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 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-Dxo3IsYq.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-Dxo3IsYq.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
|
-
/**
|
|
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
|
|
2
|
-
export {
|
|
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 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-Dxo3IsYq.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-Dxo3IsYq.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
|
-
/**
|
|
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-
|
|
2
|
-
export { InvoError } from './chunk-
|
|
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
|
|
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
|