@invonetwork/web-sdk 3.8.1 → 3.10.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,14 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-HYGBTUEJ.js';
2
- export { InvoError } from './chunk-HYGBTUEJ.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-L4A6OV54.js';
2
+ export { InvoError } from './chunk-L4A6OV54.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  // src/version.ts
6
- var SDK_VERSION = "3.8.0";
6
+ var SDK_VERSION = "3.10.0";
7
+
8
+ // src/shared/types.ts
9
+ function isRefundPendingApproval(r) {
10
+ return r.status === "pending_approval";
11
+ }
7
12
  var DEFAULT_TOLERANCE_SEC = 300;
8
13
  var ENCODER = new TextEncoder();
9
14
  function toBytes(body) {
@@ -686,6 +691,79 @@ function toSavedCard(row) {
686
691
  function nullableString(v) {
687
692
  return v == null ? null : String(v);
688
693
  }
694
+ function optionalString(r, key) {
695
+ return key in r ? nullableString(r[key]) : void 0;
696
+ }
697
+ function toRefundWarnings(v) {
698
+ if (!Array.isArray(v)) return void 0;
699
+ return v.filter((w) => !!w && typeof w === "object").map((w) => ({ code: String(w["code"] ?? ""), message: String(w["message"] ?? "") }));
700
+ }
701
+ function toRefundResult(raw, subscriptionId, clientRequestId) {
702
+ const attr = raw["revenue_share_attribution"];
703
+ const a = attr && typeof attr === "object" ? attr : null;
704
+ const base = {
705
+ status: String(raw["status"] ?? ""),
706
+ idempotentReplay: raw["idempotent_replay"] === true,
707
+ refundKey: nullableString(raw["refund_key"]),
708
+ clientRequestId: nullableString(raw["client_request_id"]) ?? clientRequestId,
709
+ subscriptionId: String(raw["subscription_id"] ?? subscriptionId),
710
+ periodSeq: raw["period_seq"] == null ? null : Number(raw["period_seq"]),
711
+ transactionId: nullableString(raw["transaction_id"]),
712
+ refundedAmountUsd: nullableString(raw["refunded_amount_usd"]),
713
+ totalRefundedAmountUsd: nullableString(raw["total_refunded_amount_usd"]),
714
+ remainingRefundableUsd: nullableString(raw["remaining_refundable_usd"]),
715
+ isFullRefund: raw["is_full_refund"] === true,
716
+ fundingShape: nullableString(raw["funding_shape"]),
717
+ balanceDeltaCoins: nullableString(raw["balance_delta_coins"]),
718
+ cardRefundedUsd: nullableString(raw["card_refunded_usd"]),
719
+ // Neutral field only; the vendor-named sibling is deliberately not read.
720
+ processorRefundReference: nullableString(raw["processor_refund_reference"]),
721
+ processorRefundAdopted: raw["processor_refund_adopted"] === true,
722
+ invoFeeRetained: raw["invo_fee_retained"] === true,
723
+ partnerRevenueReversedUsd: nullableString(raw["partner_revenue_reversed_usd"]),
724
+ partnerRevenueReversalMode: nullableString(raw["partner_revenue_reversal_mode"]),
725
+ reason: nullableString(raw["reason"]),
726
+ refundedAt: nullableString(raw["refunded_at"]),
727
+ newBalance: nullableString(raw["new_balance"]),
728
+ revenueShareAttribution: a ? {
729
+ recipientPlayerId: Number(a["recipient_player_id"] ?? 0),
730
+ percent: String(a["percent"] ?? ""),
731
+ originalAttributedAmountUsd: String(a["original_attributed_amount_usd"] ?? ""),
732
+ refundedAttributedAmountUsd: String(a["refunded_attributed_amount_usd"] ?? ""),
733
+ netAttributedAmountUsd: String(a["net_attributed_amount_usd"] ?? ""),
734
+ settledByInvo: a["settled_by_invo"] === true,
735
+ raw: a
736
+ } : null,
737
+ note: typeof raw["note"] === "string" ? raw["note"] : void 0,
738
+ // ---- additive (2026-09-17): undefined when the body predates them ----
739
+ warnings: toRefundWarnings(raw["warnings"]),
740
+ subscriptionCanceled: "subscription_canceled" in raw ? raw["subscription_canceled"] === true : void 0,
741
+ subscriptionStatus: optionalString(raw, "subscription_status"),
742
+ processingFeeUsd: optionalString(raw, "processing_fee_usd"),
743
+ processingFeeBasis: optionalString(raw, "processing_fee_basis"),
744
+ processingFeeBorneBy: optionalString(raw, "processing_fee_borne_by"),
745
+ processingFeeTransactionId: optionalString(raw, "processing_fee_transaction_id"),
746
+ partnerTotalReversedUsd: optionalString(raw, "partner_total_reversed_usd"),
747
+ initiation: optionalString(raw, "initiation"),
748
+ refundRequestId: optionalString(raw, "refund_request_id"),
749
+ raw
750
+ };
751
+ if (base.status === "pending_approval") {
752
+ const pending = {
753
+ ...base,
754
+ status: "pending_approval",
755
+ requestId: String(raw["request_id"] ?? raw["refund_request_id"] ?? ""),
756
+ requestStatus: String(raw["request_status"] ?? ""),
757
+ requestedAmountUsd: nullableString(raw["requested_amount_usd"]),
758
+ requestedAt: nullableString(raw["requested_at"]),
759
+ dailyCapUsd: nullableString(raw["daily_cap_usd"]),
760
+ executedTodayUsd: nullableString(raw["executed_today_usd"]),
761
+ message: nullableString(raw["message"])
762
+ };
763
+ return pending;
764
+ }
765
+ return base;
766
+ }
689
767
  function toSubscription(row) {
690
768
  const r = row && typeof row === "object" ? row : {};
691
769
  const share = r["revenue_share"];
@@ -733,6 +811,9 @@ function toSubscription(row) {
733
811
  } : null,
734
812
  paidThrough: nullableString(r["paid_through"]),
735
813
  amountCoinsEstimate: r["amount_coins_estimate"] == null ? void 0 : String(r["amount_coins_estimate"]),
814
+ // `include_player` puts these two ON the object (there is no separate block).
815
+ ..."player_email" in r ? { playerEmail: nullableString(r["player_email"]) } : {},
816
+ ..."player_name" in r ? { playerName: nullableString(r["player_name"]) } : {},
736
817
  raw: r
737
818
  };
738
819
  }
@@ -890,8 +971,13 @@ var SubscriptionsServer = class {
890
971
  * `err.existingSubscriptionId`) at best and a second subscription at worst. Same key
891
972
  * with different terms is `err.isIdempotentReplayMismatch` (`err.mismatchedFields`).
892
973
  *
893
- * Card selection: `playerCardId` names one (from `cards.list`); omitted, INVO attaches
894
- * the member's newest unexpired saved card; `walletOnly: true` never charges a card.
974
+ * Card only (since 2026-09-17): the card is charged the full price every period and the
975
+ * member's coin wallet never pays and never moves. Card selection: `playerCardId` names one
976
+ * (from `cards.list`); omitted, INVO attaches the member's newest unexpired saved card. With
977
+ * no saved card the subscription is still created (201) but `firstCharge` is `failed` with
978
+ * `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
979
+ * `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
980
+ * be paid (`failureCode: "wallet_only"`).
895
981
  * Requires the game to be `live` (`err.isGameNotLive`).
896
982
  */
897
983
  async create(input, opts) {
@@ -948,11 +1034,10 @@ var SubscriptionsServer = class {
948
1034
  this.auth,
949
1035
  { signal: opts?.signal }
950
1036
  );
951
- return {
952
- subscription: toSubscription(raw["subscription"]),
953
- player: raw["player"] && typeof raw["player"] === "object" ? raw["player"] : void 0,
954
- raw
955
- };
1037
+ const subscription = toSubscription(raw["subscription"]);
1038
+ const row = subscription.raw;
1039
+ const player = "player_email" in row || "player_name" in row ? { player_email: row["player_email"] ?? null, player_name: row["player_name"] ?? null } : void 0;
1040
+ return { subscription, player, raw };
956
1041
  }
957
1042
  /**
958
1043
  * List a member's subscriptions, newest first, paged (`limit` 1..100, `offset`
@@ -1093,9 +1178,9 @@ var SubscriptionsServer = class {
1093
1178
  /**
1094
1179
  * Card subscriptions only. Attach a card (`{ playerCardId }`, an `id` from
1095
1180
  * `cards.list` belonging to this player, unexpired) or make the subscription wallet-only
1096
- * (`{ walletOnly: true }`). On a wallet-only subscription pass `walletOnly: false`
1097
- * beside the card to convert it back. The new card is used from the next charge,
1098
- * including a pending retry in dunning.
1181
+ * (`{ walletOnly: true }`, deprecated: a wallet-only card subscription can never be paid).
1182
+ * On a wallet-only subscription pass `walletOnly: false` beside the card to convert it
1183
+ * back. The new card is used from the next charge, including a pending retry in dunning.
1099
1184
  *
1100
1185
  * `err.isNotACardSubscription` on Steam; `err.isSubscriptionTerminal` on a terminal row.
1101
1186
  */
@@ -1133,16 +1218,35 @@ var SubscriptionsServer = class {
1133
1218
  * Refund a billed period (card rail). Idempotent on `clientRequestId`: a repeat returns
1134
1219
  * the stored receipt with `idempotentReplay: true` and moves nothing.
1135
1220
  *
1136
- * A full refund returns the card charge and reclaims the coins that charge minted
1137
- * (`balanceDeltaCoins` is signed and can be negative); a partial refund credits the
1138
- * wallet in coins at the 10:1 peg. Your revenue is reversed for the refunded portion
1139
- * (`partnerRevenueReversedUsd`); INVO's fee is retained. The subscription is NOT
1140
- * cancelled by a refund. Refunds of Steam-CHARGED periods are not supported yet; do not
1141
- * call this on them.
1221
+ * **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
1222
+ * (HTTP 202): the refund would exceed the game's daily self-serve limit ($500 per UTC day
1223
+ * by default), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
1224
+ * outcome arrives as `subscription.refund_approved` (sent together with
1225
+ * `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
1226
+ * `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
1227
+ * (`refundedAmountUsd` is `"0.00"`; `totalRefundedAmountUsd` and `remainingRefundableUsd`
1228
+ * carry the period's real values). Check it with {@link isRefundPendingApproval}.
1229
+ *
1230
+ * A card-only period (every card period charged since 2026-09-17) is refunded in cash, full
1231
+ * or partial: `cardRefundedUsd` equals the amount and `balanceDeltaCoins` is `"0.00"`. A
1232
+ * period charged before that keeps the earlier rule: a full refund returns the card charge
1233
+ * and reclaims the coins it minted (`balanceDeltaCoins` is signed), a partial refund
1234
+ * credits coins. Your revenue is reversed for the refunded portion
1235
+ * (`partnerRevenueReversedUsd`), INVO's fee is retained, and on a card refund you bear the
1236
+ * processor fee (`processingFeeUsd`; `partnerTotalReversedUsd` is the sum). **A full refund
1237
+ * cancels the subscription** (`subscriptionCanceled`, and a `subscription.canceled` event
1238
+ * with `cancel_cause: "full_refund"`, sent together with `subscription.refunded` in any
1239
+ * order); a partial one does not. INVO emails the member.
1240
+ * Refunds run within 30 days of the period's charge. Send a `reason`: it is recommended now
1241
+ * and will be required later (`warnings` says so when it is missing).
1142
1242
  *
1143
- * Refusals: `NO_PAID_PERIOD` (409, nothing collected yet), `PERIOD_NOT_REFUNDABLE`,
1144
- * `ALREADY_REFUNDED` (`err.isAlreadyRefunded`), `AMOUNT_EXCEEDS_REMAINING` (body carries
1145
- * `remaining_refundable_usd`), `err.isFlowPaused`.
1243
+ * Refusals: `err.isRefundsNotEnabled` (403), `err.isRefundWindowClosed` (409),
1244
+ * `err.isRefundRequestPending` (409, `err.refundRequestId`), `err.isRefundRequestRejected`
1245
+ * (409, use a new key), `err.isConcurrentRequest` (409, retry with the same key),
1246
+ * `err.isRefundMismatch` (502, contact INVO), `NO_PAID_PERIOD` (409, nothing collected yet),
1247
+ * `PERIOD_NOT_REFUNDABLE`, `ALREADY_REFUNDED` (`err.isAlreadyRefunded`),
1248
+ * `AMOUNT_EXCEEDS_REMAINING` (body carries `remaining_refundable_usd`),
1249
+ * `err.isSteamRefundNotSupported`, `err.isFlowPaused`.
1146
1250
  */
1147
1251
  async refund(subscriptionId, input, opts) {
1148
1252
  assertSubscriptionId(subscriptionId);
@@ -1168,44 +1272,7 @@ var SubscriptionsServer = class {
1168
1272
  // Idempotent on client_request_id: a lost-response retry returns the stored receipt.
1169
1273
  { idempotent: true, signal: opts?.signal }
1170
1274
  );
1171
- const attr = raw["revenue_share_attribution"];
1172
- const a = attr && typeof attr === "object" ? attr : null;
1173
- return {
1174
- status: String(raw["status"] ?? ""),
1175
- idempotentReplay: raw["idempotent_replay"] === true,
1176
- refundKey: nullableString(raw["refund_key"]),
1177
- clientRequestId: nullableString(raw["client_request_id"]) ?? input.clientRequestId,
1178
- subscriptionId: String(raw["subscription_id"] ?? subscriptionId),
1179
- periodSeq: raw["period_seq"] == null ? null : Number(raw["period_seq"]),
1180
- transactionId: nullableString(raw["transaction_id"]),
1181
- refundedAmountUsd: nullableString(raw["refunded_amount_usd"]),
1182
- totalRefundedAmountUsd: nullableString(raw["total_refunded_amount_usd"]),
1183
- remainingRefundableUsd: nullableString(raw["remaining_refundable_usd"]),
1184
- isFullRefund: raw["is_full_refund"] === true,
1185
- fundingShape: nullableString(raw["funding_shape"]),
1186
- balanceDeltaCoins: nullableString(raw["balance_delta_coins"]),
1187
- cardRefundedUsd: nullableString(raw["card_refunded_usd"]),
1188
- // Neutral field only; the vendor-named sibling is deliberately not read.
1189
- processorRefundReference: nullableString(raw["processor_refund_reference"]),
1190
- processorRefundAdopted: raw["processor_refund_adopted"] === true,
1191
- invoFeeRetained: raw["invo_fee_retained"] === true,
1192
- partnerRevenueReversedUsd: nullableString(raw["partner_revenue_reversed_usd"]),
1193
- partnerRevenueReversalMode: nullableString(raw["partner_revenue_reversal_mode"]),
1194
- reason: nullableString(raw["reason"]),
1195
- refundedAt: nullableString(raw["refunded_at"]),
1196
- newBalance: nullableString(raw["new_balance"]),
1197
- revenueShareAttribution: a ? {
1198
- recipientPlayerId: Number(a["recipient_player_id"] ?? 0),
1199
- percent: String(a["percent"] ?? ""),
1200
- originalAttributedAmountUsd: String(a["original_attributed_amount_usd"] ?? ""),
1201
- refundedAttributedAmountUsd: String(a["refunded_attributed_amount_usd"] ?? ""),
1202
- netAttributedAmountUsd: String(a["net_attributed_amount_usd"] ?? ""),
1203
- settledByInvo: a["settled_by_invo"] === true,
1204
- raw: a
1205
- } : null,
1206
- note: typeof raw["note"] === "string" ? raw["note"] : void 0,
1207
- raw
1208
- };
1275
+ return toRefundResult(raw, subscriptionId, input.clientRequestId);
1209
1276
  }
1210
1277
  /**
1211
1278
  * Start a STEAM-rail subscription: creates it in `pending_steam_authorization`, opens
@@ -1321,12 +1388,81 @@ var SubscriptionsServer = class {
1321
1388
  };
1322
1389
  }
1323
1390
  };
1391
+ var SCRIPT_SCHEME = /^\s*(javascript|data|vbscript):/i;
1324
1392
  var CardsServer = class {
1325
1393
  constructor(http, auth) {
1326
1394
  this.http = http;
1327
1395
  this.auth = auth;
1328
1396
  }
1329
1397
  /**
1398
+ * Mint a short-lived session for the INVO-hosted card page and return its URL. THE
1399
+ * RECOMMENDED WAY TO SAVE A CARD FOR A SUBSCRIPTION: two server-to-server calls (this
1400
+ * one, then `cards.list`) and one redirect. No browser code, no processor script, no
1401
+ * client secret; INVO can change card processor without you changing anything.
1402
+ *
1403
+ * The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
1404
+ * never creates players. Send the member to `result.cardSetupUrl` top-level (do not
1405
+ * frame it). The page says in words that no money moves, saves the card, and then
1406
+ * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
1407
+ * appears in {@link list} immediately, carries the off-session consent a subscription
1408
+ * needs, and is indistinguishable from one saved any other way. There is no event for
1409
+ * a saved card; `cards.list` is the signal.
1410
+ *
1411
+ * The session lives 10 minutes (entering a card is one sitting); mint it when the
1412
+ * member is about to use it. The link may be reloaded freely before the save; once the
1413
+ * card is saved the link is spent and reopening it returns the same card again.
1414
+ * `successUrl` is redirected to verbatim (nothing appended) and `metadata` is stored on
1415
+ * the session and not returned anywhere today, so put your own correlation id in
1416
+ * `successUrl`.
1417
+ *
1418
+ * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
1419
+ * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
1420
+ * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
1421
+ * refuses the same values first with `status: 0`), 401 / 403 on the key or the game
1422
+ * (body `{ message }`, no code), 503 when card setup is not available right now.
1423
+ * Never auto-retried: each call mints a fresh link, so on a timeout call it again.
1424
+ */
1425
+ async createSetupSession(input, opts) {
1426
+ if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
1427
+ throw invalidInput("playerEmail", input.playerEmail, "is required");
1428
+ }
1429
+ for (const [label, value] of [
1430
+ ["successUrl", input.successUrl],
1431
+ ["cancelUrl", input.cancelUrl]
1432
+ ]) {
1433
+ if (value === void 0) continue;
1434
+ if (typeof value !== "string" || !value.trim()) throw invalidInput(label, value, "must be a non-empty URL");
1435
+ if (SCRIPT_SCHEME.test(value)) throw invalidInput(label, value, "must not use a script scheme");
1436
+ }
1437
+ if (input.metadata !== void 0 && (input.metadata === null || typeof input.metadata !== "object" || Array.isArray(input.metadata))) {
1438
+ throw invalidInput("metadata", input.metadata, "must be a plain object");
1439
+ }
1440
+ const body = { player_email: input.playerEmail };
1441
+ if (input.successUrl) body["success_url"] = input.successUrl;
1442
+ if (input.cancelUrl) body["cancel_url"] = input.cancelUrl;
1443
+ if (input.metadata) body["metadata"] = input.metadata;
1444
+ const raw = await this.http.post(
1445
+ "/api/checkout/card-setup-sessions",
1446
+ body,
1447
+ this.auth,
1448
+ { signal: opts?.signal }
1449
+ // not idempotent: every call mints a new session (same rule as createCheckout)
1450
+ );
1451
+ return {
1452
+ sessionId: String(raw["session_id"] ?? ""),
1453
+ // Load-bearing: the member must be sent here. A 2xx without it is a broken response.
1454
+ cardSetupUrl: requireField(raw["card_setup_url"], "card_setup_url", raw),
1455
+ expiresAt: String(raw["expires_at"] ?? ""),
1456
+ raw
1457
+ };
1458
+ }
1459
+ /**
1460
+ * THE PROCESSOR-BOUND ALTERNATIVE to {@link createSetupSession}. Use it only if you
1461
+ * already run a card form in your own client against INVO's current card processor:
1462
+ * the `clientSecret` it hands back can only be consumed by that processor's client
1463
+ * library, so the browser code you write for it will need rework when INVO changes
1464
+ * processor. `createSetupSession` does not have that problem.
1465
+ *
1330
1466
  * Begin saving a card (charges nothing). The player must already exist in this game
1331
1467
  * (`404 PLAYER_NOT_FOUND`). Idempotent on `setupReference`: resend the same value on a
1332
1468
  * retry and you get the same setup back (`409 SETUP_REFERENCE_REUSED` if you reuse it
@@ -1370,6 +1506,9 @@ var CardsServer = class {
1370
1506
  };
1371
1507
  }
1372
1508
  /**
1509
+ * The second half of the processor-bound alternative (see {@link beginSetup}); not
1510
+ * needed on the {@link createSetupSession} path, where INVO's page completes the save.
1511
+ *
1373
1512
  * Finish a client-confirmed setup and save the card. Idempotent on `setupIntentId`.
1374
1513
  * While the client has not finished, this throws a 400 with body
1375
1514
  * `status: "still_requires_action"`. On `500 CARD_PERSIST_FAILED` (authorised but not
@@ -1398,7 +1537,8 @@ var CardsServer = class {
1398
1537
  * A member's unexpired saved cards, newest first. An unknown player is `{ cards: [] }`.
1399
1538
  * The `id` is the value you pass as `playerCardId`; INVO never returns processor
1400
1539
  * identifiers for a card. Served from a short cache (about 60 s); a card saved through
1401
- * `beginSetup` / `confirmSetup` appears immediately.
1540
+ * the hosted card page (`createSetupSession`) or through `beginSetup` / `confirmSetup`
1541
+ * appears immediately. This read is the signal that the hosted page saved a card.
1402
1542
  */
1403
1543
  async list(playerEmail, opts) {
1404
1544
  if (typeof playerEmail !== "string" || !playerEmail.trim()) {
@@ -1457,7 +1597,8 @@ var SandboxSubscriptionsServer = class {
1457
1597
  }
1458
1598
  /**
1459
1599
  * Run the renewal immediately. **Charges the test card** (or the Steam stand-in): the
1460
- * real money path, wallet read, shortfall, mint, spend, split, `subscription.renewed`,
1600
+ * real money path (card: the full price; Steam: wallet first, then the shortfall), mint,
1601
+ * spend, split, `subscription.renewed`,
1461
1602
  * and on failure the real dunning. Read `engineStats` (`renewed: 1` on success). A
1462
1603
  * cancel-at-period-end row answers `action: "retired-at-period-end"`, `retired: true`.
1463
1604
  * `409 PERIOD_TOO_FAR_AHEAD` means you forced twice without advancing the clock.
@@ -2654,6 +2795,6 @@ var InvoServer = class {
2654
2795
  }
2655
2796
  };
2656
2797
 
2657
- export { CardsServer, InvoServer, PlatformCommerceServer, SDK_VERSION, SandboxServer, SandboxSubscriptionsServer, SubscriptionsServer, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
2798
+ export { CardsServer, InvoServer, PlatformCommerceServer, SDK_VERSION, SandboxServer, SandboxSubscriptionsServer, SubscriptionsServer, createWebhookHandler, isRefundPendingApproval, verifyWebhook, verifyWebhookAsync };
2658
2799
  //# sourceMappingURL=server.js.map
2659
2800
  //# sourceMappingURL=server.js.map