@invonetwork/web-sdk 3.12.1 → 3.14.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/index.cjs CHANGED
@@ -383,14 +383,68 @@ var InvoError = class _InvoError extends Error {
383
383
  get isAboveCardMaximum() {
384
384
  return this.code === "ABOVE_CARD_MAXIMUM";
385
385
  }
386
+ // ---- Coin purchase: INVO's card fee (2026-09-23) ----
387
+ /**
388
+ * True when an UNACKNOWLEDGED `purchaseCurrency` was refused because the amount is too
389
+ * small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged. Send a
390
+ * larger amount, or quote it with `quoteCurrencyPurchase` and send `acknowledgedTotalUsd`
391
+ * so the fee is added on top.
392
+ */
393
+ get isAmountBelowFee() {
394
+ return this.code === "AMOUNT_BELOW_FEE";
395
+ }
396
+ /**
397
+ * True when `purchaseCurrency` was sent an `acknowledgedTotalUsd` that is not the total
398
+ * INVO would charge now (`QUOTE_STALE`, 409). Nothing was charged. Quote again, show the
399
+ * player the new total, and retry with it. {@link expectedTotalUsd} carries INVO's figure.
400
+ */
401
+ get isQuoteStale() {
402
+ return this.code === "QUOTE_STALE";
403
+ }
404
+ /** On `QUOTE_STALE`: the total INVO would charge (`expected_total_usd`), decimal string. */
405
+ get expectedTotalUsd() {
406
+ const v = this.bodyObject()["expected_total_usd"];
407
+ return typeof v === "string" && v ? v : void 0;
408
+ }
409
+ /** On `QUOTE_STALE`: the total you sent, as INVO read it (`acknowledged_total_usd`). */
410
+ get acknowledgedTotalUsd() {
411
+ const v = this.bodyObject()["acknowledged_total_usd"];
412
+ return typeof v === "string" && v ? v : void 0;
413
+ }
386
414
  /**
387
415
  * True if a Platform Commerce refund targeted an order that was already refunded
388
416
  * (409). Idempotent outcome — the original refund did happen, so treat this as
389
417
  * success, not a failure to retry-loop.
390
418
  */
391
419
  get isAlreadyRefunded() {
420
+ if (this.isRefundRemainingRequiresConfirmation || this.isRefundRecentlyIssued) return false;
392
421
  return this.code === "ALREADY_REFUNDED" || this.status === 409 && /already\s+refunded/i.test(this.message);
393
422
  }
423
+ /**
424
+ * Platform Commerce card sale already refunded in part (409
425
+ * `REFUND_REMAINING_REQUIRES_CONFIRMATION`): nothing moved. Retry with
426
+ * `refundRemaining: true` to refund the rest; `refunded_total_usd` and `remaining_usd` are
427
+ * on `err.body`.
428
+ */
429
+ get isRefundRemainingRequiresConfirmation() {
430
+ return this.code === "REFUND_REMAINING_REQUIRES_CONFIRMATION";
431
+ }
432
+ /**
433
+ * A Platform Commerce refund of this order was applied in the last 120 seconds (409
434
+ * `REFUND_RECENTLY_ISSUED`): nothing moved. Re-read the order; send
435
+ * `confirmAdditionalRefund: true` to refund anyway.
436
+ */
437
+ get isRefundRecentlyIssued() {
438
+ return this.code === "REFUND_RECENTLY_ISSUED";
439
+ }
440
+ /**
441
+ * The Platform Commerce card refund failed, was canceled or still needs an action (502
442
+ * `REFUND_NOT_COMPLETED`): nothing was recorded. Retry; a refund that was in fact created
443
+ * is found and recorded on the retry, never issued twice.
444
+ */
445
+ get isRefundNotCompleted() {
446
+ return this.code === "REFUND_NOT_COMPLETED";
447
+ }
394
448
  /**
395
449
  * True when an approve / confirm-receipt was refused because the transaction is no
396
450
  * longer awaiting that step (`TRANSACTION_NOT_PENDING`, 400). `approveWithDeviceCode`
@@ -499,7 +553,8 @@ var InvoError = class _InvoError extends Error {
499
553
  * True when the same `clientRequestId` was replayed for the same player and item but
500
554
  * with DIFFERENT material terms (`IDEMPOTENT_REPLAY_MISMATCH`, 409). See
501
555
  * `mismatchedFields` (any of `amount_usd`, `interval`, `interval_count`, `wallet_only`,
502
- * `funding_rail`). To change terms use `changeAmount` / `setPaymentMethod`; to create a
556
+ * `funding_rail`, `trial_amount_usd`; for the last an omitted value counts, so a replay
557
+ * without it against a paid trial is a mismatch). To change terms use `changeAmount` / `setPaymentMethod`; to create a
503
558
  * new subscription use a new key.
504
559
  */
505
560
  get isIdempotentReplayMismatch() {
@@ -510,6 +565,46 @@ var InvoError = class _InvoError extends Error {
510
565
  const v = this.bodyObject()["mismatched_fields"];
511
566
  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
512
567
  }
568
+ // ---- Subscriptions: paid trials (2026-09-23) ----
569
+ /**
570
+ * True on `PAYMENT_METHOD_REQUIRED` (400). From `subscriptions.create`: a paid trial
571
+ * (`trialAmountUsd`) with no usable saved card; nothing was created. Save the member's card
572
+ * (`cards.createSetupSession`), then subscribe again. From `setPaymentMethod`: no
573
+ * `playerCardId` was sent.
574
+ */
575
+ get isPaymentMethodRequired() {
576
+ return this.code === "PAYMENT_METHOD_REQUIRED";
577
+ }
578
+ /**
579
+ * True when `trialAmountUsd` is not a usable trial price (`TRIAL_AMOUNT_INVALID`, 400): it
580
+ * must be a decimal of at least `0.50` (the card minimum) and less than `amountUsd`. The
581
+ * message names the rule.
582
+ */
583
+ get isTrialAmountInvalid() {
584
+ return this.code === "TRIAL_AMOUNT_INVALID";
585
+ }
586
+ /** True when `trialAmountUsd` was sent without `trialDays` or `trialEnd` (`TRIAL_AMOUNT_REQUIRES_TRIAL`, 400). */
587
+ get isTrialAmountRequiresTrial() {
588
+ return this.code === "TRIAL_AMOUNT_REQUIRES_TRIAL";
589
+ }
590
+ /**
591
+ * True when a paid trial was asked for where it cannot be charged
592
+ * (`TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING`, 400): with `walletOnly: true`, or on the Steam
593
+ * rail. Paid trials are for card subscriptions only.
594
+ */
595
+ get isTrialAmountNotSupportedForFunding() {
596
+ return this.code === "TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING";
597
+ }
598
+ /**
599
+ * True when one of the disclosed paid-trial consent fields is malformed (400):
600
+ * `CONSENT_DISCLOSED_TRIAL_AMOUNT_INVALID`, `CONSENT_DISCLOSED_TRIAL_DAYS_INVALID` (not an
601
+ * integer 1 to 365) or `CONSENT_DISCLOSED_TRIAL_END_INVALID` (not ISO 8601). `err.code`
602
+ * says which. A disclosed value that is well formed but disagrees with the trial is not
603
+ * refused; INVO records the disagreement.
604
+ */
605
+ get isConsentDisclosedTrialInvalid() {
606
+ return this.code === "CONSENT_DISCLOSED_TRIAL_AMOUNT_INVALID" || this.code === "CONSENT_DISCLOSED_TRIAL_DAYS_INVALID" || this.code === "CONSENT_DISCLOSED_TRIAL_END_INVALID";
607
+ }
513
608
  /**
514
609
  * True when `changeAmount` tried to RAISE the price of a Steam subscription
515
610
  * (`STEAM_REAUTHORIZATION_REQUIRED`, 409). The member consented to a ceiling; start a
@@ -1669,6 +1764,14 @@ async function runHostedApproval(opts, api, deps = {}) {
1669
1764
  });
1670
1765
  }
1671
1766
 
1767
+ // src/shared/receipt-fields.ts
1768
+ function receiptFields(raw) {
1769
+ const n = raw["receipt_number"];
1770
+ if (typeof n !== "string" || n === "") return {};
1771
+ const u = raw["receipt_url"];
1772
+ return typeof u === "string" && u !== "" ? { receiptNumber: n, receiptUrl: u } : { receiptNumber: n };
1773
+ }
1774
+
1672
1775
  // src/shared/purchase-status.ts
1673
1776
  function str(v) {
1674
1777
  return typeof v === "string" ? v : v === null || v === void 0 ? null : String(v);
@@ -1690,6 +1793,7 @@ function toPurchaseStatusResult(raw, sessionId) {
1690
1793
  amountChargedUsd: str(raw["amount_charged_usd"]),
1691
1794
  listedUsd: str(raw["listed_usd"]),
1692
1795
  currencyName: str(raw["currency_name"]),
1796
+ ...receiptFields(raw),
1693
1797
  raw
1694
1798
  };
1695
1799
  }
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CT0Ksonp.cjs';
2
- export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CT0Ksonp.cjs';
1
+ import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CD83iV3D.cjs';
2
+ export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CD83iV3D.cjs';
3
3
 
4
4
  /** The four device-approval flows (`begin.flow`). */
5
5
  type HostedFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
@@ -94,21 +94,6 @@ interface ApproveHostedOptions {
94
94
  signal?: AbortSignal;
95
95
  }
96
96
 
97
- /**
98
- * The purchase status read: mapping and the guards that go with it.
99
- *
100
- * WHY THE ENDPOINT EXISTS. A hosted checkout used to be able to charge a buyer in full,
101
- * refuse the credit, answer `200` on every route, and close the page on nothing: no coins,
102
- * no error, no receipt. `GET /api/checkout/sessions/<id>` is INVO's fix for that silence.
103
- * It always has something true to say, including the case where INVO has the buyer's money
104
- * and the buyer does not have their coins.
105
- *
106
- * ONE RULE RUNS THROUGH THIS FILE: `terminal` is INVO's answer, never ours. It is read
107
- * straight off the response and never recomputed from `status`, so a status a future
108
- * backend introduces cannot make a build pinned to this release decide a purchase
109
- * finished, or finished WELL, on its own.
110
- */
111
-
112
97
  /**
113
98
  * The purchase was charged and the coins are in the balance. Show `coinsCredited`,
114
99
  * `currencyName` and `newBalance` when it is not null, and close on the buyer's action
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CT0Ksonp.js';
2
- export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CT0Ksonp.js';
1
+ import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CD83iV3D.js';
2
+ export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CD83iV3D.js';
3
3
 
4
4
  /** The four device-approval flows (`begin.flow`). */
5
5
  type HostedFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
@@ -94,21 +94,6 @@ interface ApproveHostedOptions {
94
94
  signal?: AbortSignal;
95
95
  }
96
96
 
97
- /**
98
- * The purchase status read: mapping and the guards that go with it.
99
- *
100
- * WHY THE ENDPOINT EXISTS. A hosted checkout used to be able to charge a buyer in full,
101
- * refuse the credit, answer `200` on every route, and close the page on nothing: no coins,
102
- * no error, no receipt. `GET /api/checkout/sessions/<id>` is INVO's fix for that silence.
103
- * It always has something true to say, including the case where INVO has the buyer's money
104
- * and the buyer does not have their coins.
105
- *
106
- * ONE RULE RUNS THROUGH THIS FILE: `terminal` is INVO's answer, never ours. It is read
107
- * straight off the response and never recomputed from `status`, so a status a future
108
- * backend introduces cannot make a build pinned to this release decide a purchase
109
- * finished, or finished WELL, on its own.
110
- */
111
-
112
97
  /**
113
98
  * The purchase was charged and the coins are in the balance. Show `coinsCredited`,
114
99
  * `currencyName` and `newBalance` when it is not null, and close on the buyer's action
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-5BMM5ZTW.js';
2
- export { InvoError } from './chunk-5BMM5ZTW.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult, receiptFields } from './chunk-BLY4NUMG.js';
2
+ export { InvoError } from './chunk-BLY4NUMG.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {
@@ -706,6 +706,7 @@ function toPurchaseStatusResult(raw, sessionId) {
706
706
  amountChargedUsd: str(raw["amount_charged_usd"]),
707
707
  listedUsd: str(raw["listed_usd"]),
708
708
  currencyName: str(raw["currency_name"]),
709
+ ...receiptFields(raw),
709
710
  raw
710
711
  };
711
712
  }
package/dist/server.cjs CHANGED
@@ -385,14 +385,68 @@ var InvoError = class _InvoError extends Error {
385
385
  get isAboveCardMaximum() {
386
386
  return this.code === "ABOVE_CARD_MAXIMUM";
387
387
  }
388
+ // ---- Coin purchase: INVO's card fee (2026-09-23) ----
389
+ /**
390
+ * True when an UNACKNOWLEDGED `purchaseCurrency` was refused because the amount is too
391
+ * small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged. Send a
392
+ * larger amount, or quote it with `quoteCurrencyPurchase` and send `acknowledgedTotalUsd`
393
+ * so the fee is added on top.
394
+ */
395
+ get isAmountBelowFee() {
396
+ return this.code === "AMOUNT_BELOW_FEE";
397
+ }
398
+ /**
399
+ * True when `purchaseCurrency` was sent an `acknowledgedTotalUsd` that is not the total
400
+ * INVO would charge now (`QUOTE_STALE`, 409). Nothing was charged. Quote again, show the
401
+ * player the new total, and retry with it. {@link expectedTotalUsd} carries INVO's figure.
402
+ */
403
+ get isQuoteStale() {
404
+ return this.code === "QUOTE_STALE";
405
+ }
406
+ /** On `QUOTE_STALE`: the total INVO would charge (`expected_total_usd`), decimal string. */
407
+ get expectedTotalUsd() {
408
+ const v = this.bodyObject()["expected_total_usd"];
409
+ return typeof v === "string" && v ? v : void 0;
410
+ }
411
+ /** On `QUOTE_STALE`: the total you sent, as INVO read it (`acknowledged_total_usd`). */
412
+ get acknowledgedTotalUsd() {
413
+ const v = this.bodyObject()["acknowledged_total_usd"];
414
+ return typeof v === "string" && v ? v : void 0;
415
+ }
388
416
  /**
389
417
  * True if a Platform Commerce refund targeted an order that was already refunded
390
418
  * (409). Idempotent outcome — the original refund did happen, so treat this as
391
419
  * success, not a failure to retry-loop.
392
420
  */
393
421
  get isAlreadyRefunded() {
422
+ if (this.isRefundRemainingRequiresConfirmation || this.isRefundRecentlyIssued) return false;
394
423
  return this.code === "ALREADY_REFUNDED" || this.status === 409 && /already\s+refunded/i.test(this.message);
395
424
  }
425
+ /**
426
+ * Platform Commerce card sale already refunded in part (409
427
+ * `REFUND_REMAINING_REQUIRES_CONFIRMATION`): nothing moved. Retry with
428
+ * `refundRemaining: true` to refund the rest; `refunded_total_usd` and `remaining_usd` are
429
+ * on `err.body`.
430
+ */
431
+ get isRefundRemainingRequiresConfirmation() {
432
+ return this.code === "REFUND_REMAINING_REQUIRES_CONFIRMATION";
433
+ }
434
+ /**
435
+ * A Platform Commerce refund of this order was applied in the last 120 seconds (409
436
+ * `REFUND_RECENTLY_ISSUED`): nothing moved. Re-read the order; send
437
+ * `confirmAdditionalRefund: true` to refund anyway.
438
+ */
439
+ get isRefundRecentlyIssued() {
440
+ return this.code === "REFUND_RECENTLY_ISSUED";
441
+ }
442
+ /**
443
+ * The Platform Commerce card refund failed, was canceled or still needs an action (502
444
+ * `REFUND_NOT_COMPLETED`): nothing was recorded. Retry; a refund that was in fact created
445
+ * is found and recorded on the retry, never issued twice.
446
+ */
447
+ get isRefundNotCompleted() {
448
+ return this.code === "REFUND_NOT_COMPLETED";
449
+ }
396
450
  /**
397
451
  * True when an approve / confirm-receipt was refused because the transaction is no
398
452
  * longer awaiting that step (`TRANSACTION_NOT_PENDING`, 400). `approveWithDeviceCode`
@@ -501,7 +555,8 @@ var InvoError = class _InvoError extends Error {
501
555
  * True when the same `clientRequestId` was replayed for the same player and item but
502
556
  * with DIFFERENT material terms (`IDEMPOTENT_REPLAY_MISMATCH`, 409). See
503
557
  * `mismatchedFields` (any of `amount_usd`, `interval`, `interval_count`, `wallet_only`,
504
- * `funding_rail`). To change terms use `changeAmount` / `setPaymentMethod`; to create a
558
+ * `funding_rail`, `trial_amount_usd`; for the last an omitted value counts, so a replay
559
+ * without it against a paid trial is a mismatch). To change terms use `changeAmount` / `setPaymentMethod`; to create a
505
560
  * new subscription use a new key.
506
561
  */
507
562
  get isIdempotentReplayMismatch() {
@@ -512,6 +567,46 @@ var InvoError = class _InvoError extends Error {
512
567
  const v = this.bodyObject()["mismatched_fields"];
513
568
  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
514
569
  }
570
+ // ---- Subscriptions: paid trials (2026-09-23) ----
571
+ /**
572
+ * True on `PAYMENT_METHOD_REQUIRED` (400). From `subscriptions.create`: a paid trial
573
+ * (`trialAmountUsd`) with no usable saved card; nothing was created. Save the member's card
574
+ * (`cards.createSetupSession`), then subscribe again. From `setPaymentMethod`: no
575
+ * `playerCardId` was sent.
576
+ */
577
+ get isPaymentMethodRequired() {
578
+ return this.code === "PAYMENT_METHOD_REQUIRED";
579
+ }
580
+ /**
581
+ * True when `trialAmountUsd` is not a usable trial price (`TRIAL_AMOUNT_INVALID`, 400): it
582
+ * must be a decimal of at least `0.50` (the card minimum) and less than `amountUsd`. The
583
+ * message names the rule.
584
+ */
585
+ get isTrialAmountInvalid() {
586
+ return this.code === "TRIAL_AMOUNT_INVALID";
587
+ }
588
+ /** True when `trialAmountUsd` was sent without `trialDays` or `trialEnd` (`TRIAL_AMOUNT_REQUIRES_TRIAL`, 400). */
589
+ get isTrialAmountRequiresTrial() {
590
+ return this.code === "TRIAL_AMOUNT_REQUIRES_TRIAL";
591
+ }
592
+ /**
593
+ * True when a paid trial was asked for where it cannot be charged
594
+ * (`TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING`, 400): with `walletOnly: true`, or on the Steam
595
+ * rail. Paid trials are for card subscriptions only.
596
+ */
597
+ get isTrialAmountNotSupportedForFunding() {
598
+ return this.code === "TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING";
599
+ }
600
+ /**
601
+ * True when one of the disclosed paid-trial consent fields is malformed (400):
602
+ * `CONSENT_DISCLOSED_TRIAL_AMOUNT_INVALID`, `CONSENT_DISCLOSED_TRIAL_DAYS_INVALID` (not an
603
+ * integer 1 to 365) or `CONSENT_DISCLOSED_TRIAL_END_INVALID` (not ISO 8601). `err.code`
604
+ * says which. A disclosed value that is well formed but disagrees with the trial is not
605
+ * refused; INVO records the disagreement.
606
+ */
607
+ get isConsentDisclosedTrialInvalid() {
608
+ return this.code === "CONSENT_DISCLOSED_TRIAL_AMOUNT_INVALID" || this.code === "CONSENT_DISCLOSED_TRIAL_DAYS_INVALID" || this.code === "CONSENT_DISCLOSED_TRIAL_END_INVALID";
609
+ }
515
610
  /**
516
611
  * True when `changeAmount` tried to RAISE the price of a Steam subscription
517
612
  * (`STEAM_REAUTHORIZATION_REQUIRED`, 409). The member consented to a ceiling; start a
@@ -987,8 +1082,25 @@ function toDestinationsResult(raw, direction) {
987
1082
  };
988
1083
  }
989
1084
 
1085
+ // src/shared/receipt-fields.ts
1086
+ function creditFields(raw) {
1087
+ const c = raw["credited"];
1088
+ if (c === true) return { credited: true };
1089
+ if (c === false) {
1090
+ const r = raw["reason_code"];
1091
+ return { credited: false, reasonCode: r == null ? null : String(r) };
1092
+ }
1093
+ return {};
1094
+ }
1095
+ function receiptFields(raw) {
1096
+ const n = raw["receipt_number"];
1097
+ if (typeof n !== "string" || n === "") return {};
1098
+ const u = raw["receipt_url"];
1099
+ return typeof u === "string" && u !== "" ? { receiptNumber: n, receiptUrl: u } : { receiptNumber: n };
1100
+ }
1101
+
990
1102
  // src/version.ts
991
- var SDK_VERSION = "3.12.1";
1103
+ var SDK_VERSION = "3.14.0";
992
1104
 
993
1105
  // src/shared/types.ts
994
1106
  function isRefundPendingApproval(r) {
@@ -1162,6 +1274,56 @@ async function hmacHexSubtle(secret, message) {
1162
1274
  var DEFAULT_UA = `invonetwork-web-sdk/${SDK_VERSION} (+https://invo.network)`;
1163
1275
  var MAX_USD_AMOUNT = 999999.99;
1164
1276
  var MAX_ITEM_PRICE = 999999.99;
1277
+ var MAX_ACKNOWLEDGED_TOTAL_USD = 9999999999e-2;
1278
+ function assertAcknowledgedTotal(value) {
1279
+ parseMoney(value, MAX_ACKNOWLEDGED_TOTAL_USD, "acknowledgedTotalUsd");
1280
+ }
1281
+ function optionalDecimalString(v) {
1282
+ return v == null ? void 0 : String(v);
1283
+ }
1284
+ function toQuoteBreakdown(row) {
1285
+ const r = row && typeof row === "object" ? row : {};
1286
+ const nullable = (v) => v == null ? null : String(v);
1287
+ return {
1288
+ subtotalUsd: String(r["subtotal_usd"] ?? ""),
1289
+ taxUsd: String(r["tax_usd"] ?? "0.00"),
1290
+ taxTreatment: nullable(r["tax_treatment"]),
1291
+ taxNote: String(r["tax_note"] ?? ""),
1292
+ taxRatePct: nullable(r["tax_rate_pct"]),
1293
+ taxJurisdiction: nullable(r["tax_jurisdiction"]),
1294
+ processingFeeUsd: String(r["processing_fee_usd"] ?? ""),
1295
+ processingFeeNote: String(r["processing_fee_note"] ?? ""),
1296
+ totalUsd: String(r["total_usd"] ?? ""),
1297
+ coins: String(r["coins"] ?? ""),
1298
+ currencyName: String(r["currency_name"] ?? ""),
1299
+ raw: r
1300
+ };
1301
+ }
1302
+ function toUnacknowledgedOutcome(row) {
1303
+ if (!row || typeof row !== "object") return null;
1304
+ const r = row;
1305
+ return {
1306
+ chargeTotalUsd: String(r["charge_total_usd"] ?? ""),
1307
+ processingFeeUsd: String(r["processing_fee_usd"] ?? ""),
1308
+ coins: String(r["coins"] ?? ""),
1309
+ feeTakenFrom: String(r["fee_taken_from"] ?? "coins")
1310
+ };
1311
+ }
1312
+ function toCurrencyPurchaseQuote(raw) {
1313
+ const breakdown = toQuoteBreakdown(raw["breakdown"]);
1314
+ return {
1315
+ totalUsd: requireField(raw["total_usd"], "total_usd", raw),
1316
+ amountCents: Number(raw["amount_cents"] ?? 0),
1317
+ // Top-level since 2026-09-23; the breakdown has always carried the same figures.
1318
+ subtotalUsd: String(raw["subtotal_usd"] ?? breakdown.subtotalUsd),
1319
+ processingFeeUsd: String(raw["processing_fee_usd"] ?? breakdown.processingFeeUsd),
1320
+ coins: String(raw["coins"] ?? breakdown.coins),
1321
+ currencyName: String(raw["currency_name"] ?? breakdown.currencyName),
1322
+ breakdown,
1323
+ ifUnacknowledged: toUnacknowledgedOutcome(raw["if_unacknowledged"]),
1324
+ raw
1325
+ };
1326
+ }
1165
1327
  function invalidInput(label, value, why) {
1166
1328
  return new InvoError({
1167
1329
  message: `${label} ${why} (got ${JSON.stringify(value)}).`,
@@ -1215,6 +1377,7 @@ function toOrderDetails(raw) {
1215
1377
  order: raw["order"] ?? {},
1216
1378
  financialSummary: raw["financial_summary"] ?? {},
1217
1379
  statusTimeline: raw["status_timeline"] ?? null,
1380
+ ...receiptFields(raw),
1218
1381
  raw
1219
1382
  };
1220
1383
  }
@@ -1595,6 +1758,7 @@ var PlatformCommerceServer = class {
1595
1758
  usdAmount: raw["usd_amount"] ?? null,
1596
1759
  paymentMethod: raw["payment_method"],
1597
1760
  createdAt: raw["created_at"],
1761
+ ...receiptFields(raw),
1598
1762
  raw
1599
1763
  };
1600
1764
  }
@@ -1618,6 +1782,8 @@ var PlatformCommerceServer = class {
1618
1782
  if (hasOrder) body["order_id"] = input.orderId;
1619
1783
  else body["client_request_id"] = input.clientRequestId;
1620
1784
  if (input.reason) body["reason"] = input.reason;
1785
+ if (input.refundRemaining === true) body["refund_remaining"] = true;
1786
+ if (input.confirmAdditionalRefund === true) body["confirm_additional_refund"] = true;
1621
1787
  const raw = await this.http.post(
1622
1788
  "/api/platform-commerce/refund",
1623
1789
  body,
@@ -1643,6 +1809,12 @@ var PlatformCommerceServer = class {
1643
1809
  // alongside the vendor-named one for exactly this reason.
1644
1810
  processorRefundId: raw["processor_refund_reference"] ?? raw["stripe_refund_id"],
1645
1811
  feeRetained: raw["fee_retained"] === true,
1812
+ // Refunds in parts only (absent on a one-shot full refund).
1813
+ ...typeof raw["partial_refund"] === "boolean" ? { partialRefund: raw["partial_refund"] } : {},
1814
+ ...raw["adopted"] === true ? { adopted: true } : {},
1815
+ ...raw["refunded_total_usd"] != null ? { refundedTotalUsd: String(raw["refunded_total_usd"]) } : {},
1816
+ ...raw["charge_total_usd"] != null ? { chargeTotalUsd: String(raw["charge_total_usd"]) } : {},
1817
+ ...raw["remaining_usd"] != null ? { remainingUsd: String(raw["remaining_usd"]) } : {},
1646
1818
  raw
1647
1819
  };
1648
1820
  }
@@ -1779,6 +1951,7 @@ function toSubscription(row) {
1779
1951
  nextChargeAt: nullableString(r["next_charge_at"]),
1780
1952
  cancelAtPeriodEnd: r["cancel_at_period_end"] === true,
1781
1953
  trialEnd: nullableString(r["trial_end"]),
1954
+ trialAmountUsd: nullableString(r["trial_amount_usd"]),
1782
1955
  canceledAt: nullableString(r["canceled_at"]),
1783
1956
  endedAt: nullableString(r["ended_at"]),
1784
1957
  walletOnly: r["wallet_only"] === true,
@@ -1792,7 +1965,10 @@ function toSubscription(row) {
1792
1965
  consent_user_agent: nullableString(consent["consent_user_agent"]),
1793
1966
  disclosed_amount_usd: nullableString(consent["disclosed_amount_usd"]),
1794
1967
  disclosed_interval: nullableString(consent["disclosed_interval"]),
1795
- terms_version: nullableString(consent["terms_version"])
1968
+ terms_version: nullableString(consent["terms_version"]),
1969
+ disclosed_trial_amount_usd: nullableString(consent["disclosed_trial_amount_usd"]),
1970
+ disclosed_trial_days: typeof consent["disclosed_trial_days"] === "number" ? consent["disclosed_trial_days"] : null,
1971
+ disclosed_trial_end: nullableString(consent["disclosed_trial_end"])
1796
1972
  },
1797
1973
  createdAt: String(r["created_at"] ?? ""),
1798
1974
  updatedAt: String(r["updated_at"] ?? ""),
@@ -1804,6 +1980,8 @@ function toSubscription(row) {
1804
1980
  } : null,
1805
1981
  paidThrough: nullableString(r["paid_through"]),
1806
1982
  amountCoinsEstimate: r["amount_coins_estimate"] == null ? void 0 : String(r["amount_coins_estimate"]),
1983
+ // Present (possibly null) only on create/finalize bodies from 2026-09-23 on.
1984
+ ..."trial_amount_coins_estimate" in r ? { trialAmountCoinsEstimate: nullableString(r["trial_amount_coins_estimate"]) } : {},
1807
1985
  // `include_player` puts these two ON the object (there is no separate block).
1808
1986
  ..."player_email" in r ? { playerEmail: nullableString(r["player_email"]) } : {},
1809
1987
  ..."player_name" in r ? { playerName: nullableString(r["player_name"]) } : {},
@@ -1822,6 +2000,7 @@ function toFirstCharge(row) {
1822
2000
  confirmationUrl: nullableString(r["confirmation_url"]),
1823
2001
  expiresAt: nullableString(r["expires_at"]),
1824
2002
  message: nullableString(r["message"]),
2003
+ ...receiptFields(r),
1825
2004
  raw: r
1826
2005
  };
1827
2006
  }
@@ -1921,6 +2100,9 @@ function subscriptionBaseBody(input) {
1921
2100
  if (c.disclosedAmountUsd !== void 0) consent["disclosed_amount_usd"] = c.disclosedAmountUsd;
1922
2101
  if (c.disclosedInterval !== void 0) consent["disclosed_interval"] = c.disclosedInterval;
1923
2102
  if (c.termsVersion !== void 0) consent["terms_version"] = c.termsVersion;
2103
+ if (c.disclosedTrialAmountUsd !== void 0) consent["disclosed_trial_amount_usd"] = c.disclosedTrialAmountUsd;
2104
+ if (c.disclosedTrialDays !== void 0) consent["disclosed_trial_days"] = c.disclosedTrialDays;
2105
+ if (c.disclosedTrialEnd !== void 0) consent["disclosed_trial_end"] = c.disclosedTrialEnd;
1924
2106
  body["consent"] = consent;
1925
2107
  }
1926
2108
  if (input.revenueShare) {
@@ -1971,6 +2153,15 @@ var SubscriptionsServer = class {
1971
2153
  * `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
1972
2154
  * `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
1973
2155
  * be paid (`failureCode: "wallet_only"`).
2156
+ *
2157
+ * PAID TRIAL: send `trialAmountUsd` with `trialDays` or `trialEnd` (for example $1.00 for 7
2158
+ * days, then `amountUsd` monthly). Period 1 is charged the trial price inside this call, so a
2159
+ * usable saved card is required (`400 PAYMENT_METHOD_REQUIRED`, `err.isPaymentMethodRequired`),
2160
+ * `firstCharge` reports the trial charge (never `skipped_trial`), and a refused trial charge
2161
+ * ends the subscription at once (`expired`, no retry). Other refusals:
2162
+ * `err.isTrialAmountRequiresTrial`, `err.isTrialAmountNotSupportedForFunding`,
2163
+ * `err.isTrialAmountInvalid` (below $0.50, or not less than `amountUsd`),
2164
+ * `err.isConsentDisclosedTrialInvalid`.
1974
2165
  * Requires the game to be `live` (`err.isGameNotLive`).
1975
2166
  */
1976
2167
  async create(input, opts) {
@@ -1993,6 +2184,23 @@ var SubscriptionsServer = class {
1993
2184
  }
1994
2185
  body["trial_end"] = input.trialEnd;
1995
2186
  }
2187
+ if (input.trialAmountUsd !== void 0) {
2188
+ if (input.trialDays === void 0 && input.trialEnd === void 0) {
2189
+ throw new InvoError({
2190
+ message: "trialAmountUsd requires a trial: send trialDays or trialEnd with it.",
2191
+ code: "TRIAL_AMOUNT_REQUIRES_TRIAL",
2192
+ status: 0
2193
+ });
2194
+ }
2195
+ if (input.walletOnly === true) {
2196
+ throw new InvoError({
2197
+ message: "trialAmountUsd is only available on card-funded subscriptions; it cannot be combined with walletOnly: true.",
2198
+ code: "TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING",
2199
+ status: 0
2200
+ });
2201
+ }
2202
+ body["trial_amount_usd"] = subscriptionMoney(input.trialAmountUsd, "trialAmountUsd");
2203
+ }
1996
2204
  if (input.walletOnly !== void 0) {
1997
2205
  if (typeof input.walletOnly !== "boolean") {
1998
2206
  throw invalidInput("walletOnly", input.walletOnly, "must be a boolean");
@@ -2313,6 +2521,13 @@ var SubscriptionsServer = class {
2313
2521
  throw invalidInput("intervalCount", input.intervalCount, "must be 1 on the Steam rail (monthly and yearly only)");
2314
2522
  }
2315
2523
  const forbidden = input;
2524
+ if (forbidden["trialAmountUsd"] !== void 0) {
2525
+ throw new InvoError({
2526
+ message: "trialAmountUsd is only available on card-funded subscriptions (subscriptions.create). Steam subscriptions have no trials.",
2527
+ code: "TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING",
2528
+ status: 0
2529
+ });
2530
+ }
2316
2531
  for (const k of ["trialDays", "trialEnd", "walletOnly", "playerCardId"]) {
2317
2532
  if (forbidden[k] !== void 0) {
2318
2533
  throw invalidInput(k, forbidden[k], "is not available on the Steam rail");
@@ -2782,6 +2997,18 @@ var InvoServer = class {
2782
2997
  * (run client-side 3-D Secure with clientSecret, then call confirmPayment).
2783
2998
  * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
2784
2999
  * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
3000
+ *
3001
+ * INVO's card fee (3.5% + $0.30 on Open, 5% + $0.30 on Merchant of Record, never less than the card cost). Two shapes, chosen by
3002
+ * what you send:
3003
+ * - with `acknowledgedTotalUsd` (the `totalUsd` from {@link quoteCurrencyPurchase}): the
3004
+ * card is charged that total and the coins are priced off `usdAmount`. A total that no
3005
+ * longer matches throws `409 QUOTE_STALE` (`err.isQuoteStale`); nothing was charged.
3006
+ * - without it: the card is charged exactly `usdAmount`, never more, and the fee comes out
3007
+ * of the coins. An amount too small to carry the fee throws `400 AMOUNT_BELOW_FEE`
3008
+ * (`err.isAmountBelowFee`); nothing was charged.
3009
+ *
3010
+ * A `success` result reports `processingFeeUsd`, `feeTakenFrom`, `coinsCredited` and
3011
+ * `chargeTotalUsd`.
2785
3012
  */
2786
3013
  async purchaseCurrency(input, opts) {
2787
3014
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
@@ -2807,6 +3034,10 @@ var InvoServer = class {
2807
3034
  usd_amount: input.usdAmount,
2808
3035
  purchase_reference: input.purchaseReference
2809
3036
  };
3037
+ if (input.acknowledgedTotalUsd !== void 0) {
3038
+ assertAcknowledgedTotal(input.acknowledgedTotalUsd);
3039
+ body["acknowledged_total_usd"] = input.acknowledgedTotalUsd;
3040
+ }
2810
3041
  if (input.rail) body["rail"] = input.rail;
2811
3042
  if (input.paymentMethodId) body["payment_method_id"] = input.paymentMethodId;
2812
3043
  if (input.savedCardId) body["saved_card_id"] = input.savedCardId;
@@ -2828,10 +3059,53 @@ var InvoServer = class {
2828
3059
  transactionId: raw["transaction_id"],
2829
3060
  orderId: raw["order_id"],
2830
3061
  newBalance: raw["new_balance"] ?? null,
3062
+ processingFeeUsd: optionalDecimalString(raw["processing_fee_usd"]),
3063
+ feeTakenFrom: optionalDecimalString(raw["fee_taken_from"]),
3064
+ coinsCredited: optionalDecimalString(raw["coins_credited"]),
3065
+ chargeTotalUsd: optionalDecimalString(raw["charge_total_usd"]),
3066
+ ...receiptFields(raw),
2831
3067
  raw
2832
3068
  };
2833
3069
  }
2834
- /** Complete the card-rail 3-D Secure step after the client finished card action. */
3070
+ /**
3071
+ * What a card purchase of coins will cost, BEFORE charging for it. Moves no money and
3072
+ * creates nothing, so it is safe to call on every price render (`POST
3073
+ * /api/currency-purchases/quote`, authenticated by your game secret like the purchase).
3074
+ *
3075
+ * INVO's card fee on a coin purchase is 3.5% + $0.30 of the price on the Open tier (5% + $0.30 on Merchant of Record), never less than the
3076
+ * card cost. `totalUsd` is the price plus that fee (plus any tax, when you pass `country`):
3077
+ * $10.00 quotes a $10.65 total. Show the player `totalUsd`, then send the same figure back
3078
+ * as `acknowledgedTotalUsd` on {@link purchaseCurrency}; the card is charged exactly that
3079
+ * and the player gets the coins for the full price. `ifUnacknowledged` shows the other
3080
+ * outcome: the card charged exactly `usdAmount` and the fee taken out of the coins ($10.00
3081
+ * gives 93.70 coins at the default 10 per USD), or `null` when the amount cannot carry the
3082
+ * fee.
3083
+ *
3084
+ * Refusals: `400 INVALID_INPUT` (amount missing, not above zero, or above INVO's card
3085
+ * maximum), `400 CURRENCY_NOT_CONFIGURED`, `503 RATE_UNAVAILABLE`.
3086
+ */
3087
+ async quoteCurrencyPurchase(input, opts) {
3088
+ assertUsdAmount(input.usdAmount);
3089
+ const body = {
3090
+ player_email: input.playerEmail,
3091
+ usd_amount: input.usdAmount
3092
+ };
3093
+ if (input.country) body["country"] = input.country;
3094
+ if (input.subdivision) body["subdivision"] = input.subdivision;
3095
+ const raw = await this.http.post(
3096
+ "/api/currency-purchases/quote",
3097
+ body,
3098
+ this.auth,
3099
+ { idempotent: true, signal: opts?.signal }
3100
+ // a read: it moves no money and creates nothing
3101
+ );
3102
+ return toCurrencyPurchaseQuote(raw);
3103
+ }
3104
+ /**
3105
+ * Complete the card-rail 3-D Secure step after the client finished card action.
3106
+ * `status: "success"` means the payment succeeded; tell the buyer the purchase is complete
3107
+ * only when `credited` is `true` (see {@link ConfirmPaymentResult.credited}).
3108
+ */
2835
3109
  async confirmPayment(input, opts) {
2836
3110
  const body = { payment_intent_id: input.paymentIntentId };
2837
3111
  if (input.orderId) body["order_id"] = input.orderId;
@@ -2846,6 +3120,7 @@ var InvoServer = class {
2846
3120
  status: String(raw["status"] ?? ""),
2847
3121
  transactionId: raw["transaction_id"],
2848
3122
  newBalance: raw["new_balance"] ?? null,
3123
+ ...creditFields(raw),
2849
3124
  raw
2850
3125
  };
2851
3126
  }
@@ -3009,6 +3284,7 @@ var InvoServer = class {
3009
3284
  transactionId: raw["transaction_id"] ?? void 0,
3010
3285
  newBalance: raw["new_balance"] ?? null,
3011
3286
  alreadyProcessed: raw["already_processed"] === true,
3287
+ ...creditFields(raw),
3012
3288
  raw
3013
3289
  };
3014
3290
  }