@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/server.js CHANGED
@@ -1,9 +1,9 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-5BMM5ZTW.js';
2
- export { InvoError } from './chunk-5BMM5ZTW.js';
1
+ import { InvoError, receiptFields, assertSecureBaseUrl, Http, creditFields, toDestinationsResult } from './chunk-BLY4NUMG.js';
2
+ export { InvoError } from './chunk-BLY4NUMG.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  // src/version.ts
6
- var SDK_VERSION = "3.12.1";
6
+ var SDK_VERSION = "3.14.0";
7
7
 
8
8
  // src/shared/types.ts
9
9
  function isRefundPendingApproval(r) {
@@ -177,6 +177,56 @@ async function hmacHexSubtle(secret, message) {
177
177
  var DEFAULT_UA = `invonetwork-web-sdk/${SDK_VERSION} (+https://invo.network)`;
178
178
  var MAX_USD_AMOUNT = 999999.99;
179
179
  var MAX_ITEM_PRICE = 999999.99;
180
+ var MAX_ACKNOWLEDGED_TOTAL_USD = 9999999999e-2;
181
+ function assertAcknowledgedTotal(value) {
182
+ parseMoney(value, MAX_ACKNOWLEDGED_TOTAL_USD, "acknowledgedTotalUsd");
183
+ }
184
+ function optionalDecimalString(v) {
185
+ return v == null ? void 0 : String(v);
186
+ }
187
+ function toQuoteBreakdown(row) {
188
+ const r = row && typeof row === "object" ? row : {};
189
+ const nullable = (v) => v == null ? null : String(v);
190
+ return {
191
+ subtotalUsd: String(r["subtotal_usd"] ?? ""),
192
+ taxUsd: String(r["tax_usd"] ?? "0.00"),
193
+ taxTreatment: nullable(r["tax_treatment"]),
194
+ taxNote: String(r["tax_note"] ?? ""),
195
+ taxRatePct: nullable(r["tax_rate_pct"]),
196
+ taxJurisdiction: nullable(r["tax_jurisdiction"]),
197
+ processingFeeUsd: String(r["processing_fee_usd"] ?? ""),
198
+ processingFeeNote: String(r["processing_fee_note"] ?? ""),
199
+ totalUsd: String(r["total_usd"] ?? ""),
200
+ coins: String(r["coins"] ?? ""),
201
+ currencyName: String(r["currency_name"] ?? ""),
202
+ raw: r
203
+ };
204
+ }
205
+ function toUnacknowledgedOutcome(row) {
206
+ if (!row || typeof row !== "object") return null;
207
+ const r = row;
208
+ return {
209
+ chargeTotalUsd: String(r["charge_total_usd"] ?? ""),
210
+ processingFeeUsd: String(r["processing_fee_usd"] ?? ""),
211
+ coins: String(r["coins"] ?? ""),
212
+ feeTakenFrom: String(r["fee_taken_from"] ?? "coins")
213
+ };
214
+ }
215
+ function toCurrencyPurchaseQuote(raw) {
216
+ const breakdown = toQuoteBreakdown(raw["breakdown"]);
217
+ return {
218
+ totalUsd: requireField(raw["total_usd"], "total_usd", raw),
219
+ amountCents: Number(raw["amount_cents"] ?? 0),
220
+ // Top-level since 2026-09-23; the breakdown has always carried the same figures.
221
+ subtotalUsd: String(raw["subtotal_usd"] ?? breakdown.subtotalUsd),
222
+ processingFeeUsd: String(raw["processing_fee_usd"] ?? breakdown.processingFeeUsd),
223
+ coins: String(raw["coins"] ?? breakdown.coins),
224
+ currencyName: String(raw["currency_name"] ?? breakdown.currencyName),
225
+ breakdown,
226
+ ifUnacknowledged: toUnacknowledgedOutcome(raw["if_unacknowledged"]),
227
+ raw
228
+ };
229
+ }
180
230
  function invalidInput(label, value, why) {
181
231
  return new InvoError({
182
232
  message: `${label} ${why} (got ${JSON.stringify(value)}).`,
@@ -230,6 +280,7 @@ function toOrderDetails(raw) {
230
280
  order: raw["order"] ?? {},
231
281
  financialSummary: raw["financial_summary"] ?? {},
232
282
  statusTimeline: raw["status_timeline"] ?? null,
283
+ ...receiptFields(raw),
233
284
  raw
234
285
  };
235
286
  }
@@ -610,6 +661,7 @@ var PlatformCommerceServer = class {
610
661
  usdAmount: raw["usd_amount"] ?? null,
611
662
  paymentMethod: raw["payment_method"],
612
663
  createdAt: raw["created_at"],
664
+ ...receiptFields(raw),
613
665
  raw
614
666
  };
615
667
  }
@@ -633,6 +685,8 @@ var PlatformCommerceServer = class {
633
685
  if (hasOrder) body["order_id"] = input.orderId;
634
686
  else body["client_request_id"] = input.clientRequestId;
635
687
  if (input.reason) body["reason"] = input.reason;
688
+ if (input.refundRemaining === true) body["refund_remaining"] = true;
689
+ if (input.confirmAdditionalRefund === true) body["confirm_additional_refund"] = true;
636
690
  const raw = await this.http.post(
637
691
  "/api/platform-commerce/refund",
638
692
  body,
@@ -658,6 +712,12 @@ var PlatformCommerceServer = class {
658
712
  // alongside the vendor-named one for exactly this reason.
659
713
  processorRefundId: raw["processor_refund_reference"] ?? raw["stripe_refund_id"],
660
714
  feeRetained: raw["fee_retained"] === true,
715
+ // Refunds in parts only (absent on a one-shot full refund).
716
+ ...typeof raw["partial_refund"] === "boolean" ? { partialRefund: raw["partial_refund"] } : {},
717
+ ...raw["adopted"] === true ? { adopted: true } : {},
718
+ ...raw["refunded_total_usd"] != null ? { refundedTotalUsd: String(raw["refunded_total_usd"]) } : {},
719
+ ...raw["charge_total_usd"] != null ? { chargeTotalUsd: String(raw["charge_total_usd"]) } : {},
720
+ ...raw["remaining_usd"] != null ? { remainingUsd: String(raw["remaining_usd"]) } : {},
661
721
  raw
662
722
  };
663
723
  }
@@ -794,6 +854,7 @@ function toSubscription(row) {
794
854
  nextChargeAt: nullableString(r["next_charge_at"]),
795
855
  cancelAtPeriodEnd: r["cancel_at_period_end"] === true,
796
856
  trialEnd: nullableString(r["trial_end"]),
857
+ trialAmountUsd: nullableString(r["trial_amount_usd"]),
797
858
  canceledAt: nullableString(r["canceled_at"]),
798
859
  endedAt: nullableString(r["ended_at"]),
799
860
  walletOnly: r["wallet_only"] === true,
@@ -807,7 +868,10 @@ function toSubscription(row) {
807
868
  consent_user_agent: nullableString(consent["consent_user_agent"]),
808
869
  disclosed_amount_usd: nullableString(consent["disclosed_amount_usd"]),
809
870
  disclosed_interval: nullableString(consent["disclosed_interval"]),
810
- terms_version: nullableString(consent["terms_version"])
871
+ terms_version: nullableString(consent["terms_version"]),
872
+ disclosed_trial_amount_usd: nullableString(consent["disclosed_trial_amount_usd"]),
873
+ disclosed_trial_days: typeof consent["disclosed_trial_days"] === "number" ? consent["disclosed_trial_days"] : null,
874
+ disclosed_trial_end: nullableString(consent["disclosed_trial_end"])
811
875
  },
812
876
  createdAt: String(r["created_at"] ?? ""),
813
877
  updatedAt: String(r["updated_at"] ?? ""),
@@ -819,6 +883,8 @@ function toSubscription(row) {
819
883
  } : null,
820
884
  paidThrough: nullableString(r["paid_through"]),
821
885
  amountCoinsEstimate: r["amount_coins_estimate"] == null ? void 0 : String(r["amount_coins_estimate"]),
886
+ // Present (possibly null) only on create/finalize bodies from 2026-09-23 on.
887
+ ..."trial_amount_coins_estimate" in r ? { trialAmountCoinsEstimate: nullableString(r["trial_amount_coins_estimate"]) } : {},
822
888
  // `include_player` puts these two ON the object (there is no separate block).
823
889
  ..."player_email" in r ? { playerEmail: nullableString(r["player_email"]) } : {},
824
890
  ..."player_name" in r ? { playerName: nullableString(r["player_name"]) } : {},
@@ -837,6 +903,7 @@ function toFirstCharge(row) {
837
903
  confirmationUrl: nullableString(r["confirmation_url"]),
838
904
  expiresAt: nullableString(r["expires_at"]),
839
905
  message: nullableString(r["message"]),
906
+ ...receiptFields(r),
840
907
  raw: r
841
908
  };
842
909
  }
@@ -936,6 +1003,9 @@ function subscriptionBaseBody(input) {
936
1003
  if (c.disclosedAmountUsd !== void 0) consent["disclosed_amount_usd"] = c.disclosedAmountUsd;
937
1004
  if (c.disclosedInterval !== void 0) consent["disclosed_interval"] = c.disclosedInterval;
938
1005
  if (c.termsVersion !== void 0) consent["terms_version"] = c.termsVersion;
1006
+ if (c.disclosedTrialAmountUsd !== void 0) consent["disclosed_trial_amount_usd"] = c.disclosedTrialAmountUsd;
1007
+ if (c.disclosedTrialDays !== void 0) consent["disclosed_trial_days"] = c.disclosedTrialDays;
1008
+ if (c.disclosedTrialEnd !== void 0) consent["disclosed_trial_end"] = c.disclosedTrialEnd;
939
1009
  body["consent"] = consent;
940
1010
  }
941
1011
  if (input.revenueShare) {
@@ -986,6 +1056,15 @@ var SubscriptionsServer = class {
986
1056
  * `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
987
1057
  * `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
988
1058
  * be paid (`failureCode: "wallet_only"`).
1059
+ *
1060
+ * PAID TRIAL: send `trialAmountUsd` with `trialDays` or `trialEnd` (for example $1.00 for 7
1061
+ * days, then `amountUsd` monthly). Period 1 is charged the trial price inside this call, so a
1062
+ * usable saved card is required (`400 PAYMENT_METHOD_REQUIRED`, `err.isPaymentMethodRequired`),
1063
+ * `firstCharge` reports the trial charge (never `skipped_trial`), and a refused trial charge
1064
+ * ends the subscription at once (`expired`, no retry). Other refusals:
1065
+ * `err.isTrialAmountRequiresTrial`, `err.isTrialAmountNotSupportedForFunding`,
1066
+ * `err.isTrialAmountInvalid` (below $0.50, or not less than `amountUsd`),
1067
+ * `err.isConsentDisclosedTrialInvalid`.
989
1068
  * Requires the game to be `live` (`err.isGameNotLive`).
990
1069
  */
991
1070
  async create(input, opts) {
@@ -1008,6 +1087,23 @@ var SubscriptionsServer = class {
1008
1087
  }
1009
1088
  body["trial_end"] = input.trialEnd;
1010
1089
  }
1090
+ if (input.trialAmountUsd !== void 0) {
1091
+ if (input.trialDays === void 0 && input.trialEnd === void 0) {
1092
+ throw new InvoError({
1093
+ message: "trialAmountUsd requires a trial: send trialDays or trialEnd with it.",
1094
+ code: "TRIAL_AMOUNT_REQUIRES_TRIAL",
1095
+ status: 0
1096
+ });
1097
+ }
1098
+ if (input.walletOnly === true) {
1099
+ throw new InvoError({
1100
+ message: "trialAmountUsd is only available on card-funded subscriptions; it cannot be combined with walletOnly: true.",
1101
+ code: "TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING",
1102
+ status: 0
1103
+ });
1104
+ }
1105
+ body["trial_amount_usd"] = subscriptionMoney(input.trialAmountUsd, "trialAmountUsd");
1106
+ }
1011
1107
  if (input.walletOnly !== void 0) {
1012
1108
  if (typeof input.walletOnly !== "boolean") {
1013
1109
  throw invalidInput("walletOnly", input.walletOnly, "must be a boolean");
@@ -1328,6 +1424,13 @@ var SubscriptionsServer = class {
1328
1424
  throw invalidInput("intervalCount", input.intervalCount, "must be 1 on the Steam rail (monthly and yearly only)");
1329
1425
  }
1330
1426
  const forbidden = input;
1427
+ if (forbidden["trialAmountUsd"] !== void 0) {
1428
+ throw new InvoError({
1429
+ message: "trialAmountUsd is only available on card-funded subscriptions (subscriptions.create). Steam subscriptions have no trials.",
1430
+ code: "TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING",
1431
+ status: 0
1432
+ });
1433
+ }
1331
1434
  for (const k of ["trialDays", "trialEnd", "walletOnly", "playerCardId"]) {
1332
1435
  if (forbidden[k] !== void 0) {
1333
1436
  throw invalidInput(k, forbidden[k], "is not available on the Steam rail");
@@ -1797,6 +1900,18 @@ var InvoServer = class {
1797
1900
  * (run client-side 3-D Secure with clientSecret, then call confirmPayment).
1798
1901
  * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
1799
1902
  * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
1903
+ *
1904
+ * 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
1905
+ * what you send:
1906
+ * - with `acknowledgedTotalUsd` (the `totalUsd` from {@link quoteCurrencyPurchase}): the
1907
+ * card is charged that total and the coins are priced off `usdAmount`. A total that no
1908
+ * longer matches throws `409 QUOTE_STALE` (`err.isQuoteStale`); nothing was charged.
1909
+ * - without it: the card is charged exactly `usdAmount`, never more, and the fee comes out
1910
+ * of the coins. An amount too small to carry the fee throws `400 AMOUNT_BELOW_FEE`
1911
+ * (`err.isAmountBelowFee`); nothing was charged.
1912
+ *
1913
+ * A `success` result reports `processingFeeUsd`, `feeTakenFrom`, `coinsCredited` and
1914
+ * `chargeTotalUsd`.
1800
1915
  */
1801
1916
  async purchaseCurrency(input, opts) {
1802
1917
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
@@ -1822,6 +1937,10 @@ var InvoServer = class {
1822
1937
  usd_amount: input.usdAmount,
1823
1938
  purchase_reference: input.purchaseReference
1824
1939
  };
1940
+ if (input.acknowledgedTotalUsd !== void 0) {
1941
+ assertAcknowledgedTotal(input.acknowledgedTotalUsd);
1942
+ body["acknowledged_total_usd"] = input.acknowledgedTotalUsd;
1943
+ }
1825
1944
  if (input.rail) body["rail"] = input.rail;
1826
1945
  if (input.paymentMethodId) body["payment_method_id"] = input.paymentMethodId;
1827
1946
  if (input.savedCardId) body["saved_card_id"] = input.savedCardId;
@@ -1843,10 +1962,53 @@ var InvoServer = class {
1843
1962
  transactionId: raw["transaction_id"],
1844
1963
  orderId: raw["order_id"],
1845
1964
  newBalance: raw["new_balance"] ?? null,
1965
+ processingFeeUsd: optionalDecimalString(raw["processing_fee_usd"]),
1966
+ feeTakenFrom: optionalDecimalString(raw["fee_taken_from"]),
1967
+ coinsCredited: optionalDecimalString(raw["coins_credited"]),
1968
+ chargeTotalUsd: optionalDecimalString(raw["charge_total_usd"]),
1969
+ ...receiptFields(raw),
1846
1970
  raw
1847
1971
  };
1848
1972
  }
1849
- /** Complete the card-rail 3-D Secure step after the client finished card action. */
1973
+ /**
1974
+ * What a card purchase of coins will cost, BEFORE charging for it. Moves no money and
1975
+ * creates nothing, so it is safe to call on every price render (`POST
1976
+ * /api/currency-purchases/quote`, authenticated by your game secret like the purchase).
1977
+ *
1978
+ * 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
1979
+ * card cost. `totalUsd` is the price plus that fee (plus any tax, when you pass `country`):
1980
+ * $10.00 quotes a $10.65 total. Show the player `totalUsd`, then send the same figure back
1981
+ * as `acknowledgedTotalUsd` on {@link purchaseCurrency}; the card is charged exactly that
1982
+ * and the player gets the coins for the full price. `ifUnacknowledged` shows the other
1983
+ * outcome: the card charged exactly `usdAmount` and the fee taken out of the coins ($10.00
1984
+ * gives 93.70 coins at the default 10 per USD), or `null` when the amount cannot carry the
1985
+ * fee.
1986
+ *
1987
+ * Refusals: `400 INVALID_INPUT` (amount missing, not above zero, or above INVO's card
1988
+ * maximum), `400 CURRENCY_NOT_CONFIGURED`, `503 RATE_UNAVAILABLE`.
1989
+ */
1990
+ async quoteCurrencyPurchase(input, opts) {
1991
+ assertUsdAmount(input.usdAmount);
1992
+ const body = {
1993
+ player_email: input.playerEmail,
1994
+ usd_amount: input.usdAmount
1995
+ };
1996
+ if (input.country) body["country"] = input.country;
1997
+ if (input.subdivision) body["subdivision"] = input.subdivision;
1998
+ const raw = await this.http.post(
1999
+ "/api/currency-purchases/quote",
2000
+ body,
2001
+ this.auth,
2002
+ { idempotent: true, signal: opts?.signal }
2003
+ // a read: it moves no money and creates nothing
2004
+ );
2005
+ return toCurrencyPurchaseQuote(raw);
2006
+ }
2007
+ /**
2008
+ * Complete the card-rail 3-D Secure step after the client finished card action.
2009
+ * `status: "success"` means the payment succeeded; tell the buyer the purchase is complete
2010
+ * only when `credited` is `true` (see {@link ConfirmPaymentResult.credited}).
2011
+ */
1850
2012
  async confirmPayment(input, opts) {
1851
2013
  const body = { payment_intent_id: input.paymentIntentId };
1852
2014
  if (input.orderId) body["order_id"] = input.orderId;
@@ -1861,6 +2023,7 @@ var InvoServer = class {
1861
2023
  status: String(raw["status"] ?? ""),
1862
2024
  transactionId: raw["transaction_id"],
1863
2025
  newBalance: raw["new_balance"] ?? null,
2026
+ ...creditFields(raw),
1864
2027
  raw
1865
2028
  };
1866
2029
  }
@@ -2024,6 +2187,7 @@ var InvoServer = class {
2024
2187
  transactionId: raw["transaction_id"] ?? void 0,
2025
2188
  newBalance: raw["new_balance"] ?? null,
2026
2189
  alreadyProcessed: raw["already_processed"] === true,
2190
+ ...creditFields(raw),
2027
2191
  raw
2028
2192
  };
2029
2193
  }