@invonetwork/web-sdk 3.1.0 → 3.2.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.
@@ -4,6 +4,7 @@ var InvoError = class _InvoError extends Error {
4
4
  super(args.message);
5
5
  this.name = "InvoError";
6
6
  this.code = args.code;
7
+ this.rawCode = args.rawCode ?? args.code;
7
8
  this.status = args.status;
8
9
  this.body = args.body ?? null;
9
10
  this.requestId = args.requestId;
@@ -211,10 +212,44 @@ var InvoError = class _InvoError extends Error {
211
212
  get isAmountBelowMinimum() {
212
213
  return this.code === "AMOUNT_BELOW_MINIMUM";
213
214
  }
215
+ /**
216
+ * True if the `rail` you sent disagrees with the storefront key you
217
+ * authenticated with (`RAIL_CHANNEL_MISMATCH`, 400).
218
+ *
219
+ * A storefront key already determines the rail, so the fix is to stop sending
220
+ * `rail` — not to send a different one. The error body carries `channel` and
221
+ * `rail` so you can see which storefront the key belongs to.
222
+ *
223
+ * INVO refuses rather than silently overriding, because silently overriding
224
+ * would bill a player through a route you did not ask for.
225
+ */
226
+ get isRailChannelMismatch() {
227
+ return this.code === "RAIL_CHANNEL_MISMATCH";
228
+ }
229
+ /**
230
+ * True if a Steam purchase was attempted for a title INVO has not registered
231
+ * as distributed on Steam (`STEAM_RAIL_NOT_ENTITLED`, 403).
232
+ *
233
+ * Holding a `steam` storefront key does not by itself register the title —
234
+ * only INVO can do that. This is not retryable; contact INVO.
235
+ */
236
+ get isSteamRailNotEntitled() {
237
+ return this.code === "STEAM_RAIL_NOT_ENTITLED";
238
+ }
239
+ /**
240
+ * True if a title distributed on Steam tried to sell currency on a non-Steam
241
+ * rail (`STEAM_PURCHASE_LAYER_REQUIRED`, 409).
242
+ *
243
+ * Currency for a Steam title must be bought through Steam. Use the dedicated
244
+ * Steam purchase flow. Not retryable on the same rail.
245
+ */
246
+ get isSteamPurchaseLayerRequired() {
247
+ return this.code === "STEAM_PURCHASE_LAYER_REQUIRED";
248
+ }
214
249
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
215
250
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
216
251
  get isBelowCardMinimum() {
217
- return this.code === "BELOW_STRIPE_MINIMUM";
252
+ return this.code === "BELOW_CARD_MINIMUM" || this.rawCode === "BELOW_STRIPE_MINIMUM";
218
253
  }
219
254
  /** True if a Platform Commerce CARD purchase exceeded the hosted checkout's single-charge
220
255
  * cap of $999.99 (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. */
@@ -244,10 +279,12 @@ var InvoError = class _InvoError extends Error {
244
279
  function errorFromResponse(status, body, requestId) {
245
280
  let message = `INVO request failed (HTTP ${status})`;
246
281
  let code;
282
+ let rawCode;
247
283
  if (body && typeof body === "object") {
248
284
  const b = body;
249
- if (typeof b["code"] === "string") code = b["code"];
250
- else if (typeof b["error_code"] === "string") code = b["error_code"];
285
+ if (typeof b["code"] === "string") rawCode = b["code"];
286
+ else if (typeof b["error_code"] === "string") rawCode = b["error_code"];
287
+ code = typeof b["error_code_public"] === "string" ? b["error_code_public"] : rawCode;
251
288
  if (typeof b["error"] === "string") message = b["error"];
252
289
  else if (typeof b["message"] === "string") message = b["message"];
253
290
  if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited|service_unavailable)$/.test(
@@ -259,7 +296,7 @@ function errorFromResponse(status, body, requestId) {
259
296
  } else if (typeof body === "string" && body.trim()) {
260
297
  message = body;
261
298
  }
262
- return new InvoError({ message, code, status, body, requestId });
299
+ return new InvoError({ message, code, rawCode, status, body, requestId });
263
300
  }
264
301
 
265
302
  // src/shared/http.ts
@@ -507,5 +544,5 @@ function toDestinationsResult(raw, direction) {
507
544
  }
508
545
 
509
546
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
510
- //# sourceMappingURL=chunk-BPZJ63RM.js.map
511
- //# sourceMappingURL=chunk-BPZJ63RM.js.map
547
+ //# sourceMappingURL=chunk-ZLPMCR5Q.js.map
548
+ //# sourceMappingURL=chunk-ZLPMCR5Q.js.map
package/dist/index.cjs CHANGED
@@ -6,6 +6,7 @@ var InvoError = class _InvoError extends Error {
6
6
  super(args.message);
7
7
  this.name = "InvoError";
8
8
  this.code = args.code;
9
+ this.rawCode = args.rawCode ?? args.code;
9
10
  this.status = args.status;
10
11
  this.body = args.body ?? null;
11
12
  this.requestId = args.requestId;
@@ -213,10 +214,44 @@ var InvoError = class _InvoError extends Error {
213
214
  get isAmountBelowMinimum() {
214
215
  return this.code === "AMOUNT_BELOW_MINIMUM";
215
216
  }
217
+ /**
218
+ * True if the `rail` you sent disagrees with the storefront key you
219
+ * authenticated with (`RAIL_CHANNEL_MISMATCH`, 400).
220
+ *
221
+ * A storefront key already determines the rail, so the fix is to stop sending
222
+ * `rail` — not to send a different one. The error body carries `channel` and
223
+ * `rail` so you can see which storefront the key belongs to.
224
+ *
225
+ * INVO refuses rather than silently overriding, because silently overriding
226
+ * would bill a player through a route you did not ask for.
227
+ */
228
+ get isRailChannelMismatch() {
229
+ return this.code === "RAIL_CHANNEL_MISMATCH";
230
+ }
231
+ /**
232
+ * True if a Steam purchase was attempted for a title INVO has not registered
233
+ * as distributed on Steam (`STEAM_RAIL_NOT_ENTITLED`, 403).
234
+ *
235
+ * Holding a `steam` storefront key does not by itself register the title —
236
+ * only INVO can do that. This is not retryable; contact INVO.
237
+ */
238
+ get isSteamRailNotEntitled() {
239
+ return this.code === "STEAM_RAIL_NOT_ENTITLED";
240
+ }
241
+ /**
242
+ * True if a title distributed on Steam tried to sell currency on a non-Steam
243
+ * rail (`STEAM_PURCHASE_LAYER_REQUIRED`, 409).
244
+ *
245
+ * Currency for a Steam title must be bought through Steam. Use the dedicated
246
+ * Steam purchase flow. Not retryable on the same rail.
247
+ */
248
+ get isSteamPurchaseLayerRequired() {
249
+ return this.code === "STEAM_PURCHASE_LAYER_REQUIRED";
250
+ }
216
251
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
217
252
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
218
253
  get isBelowCardMinimum() {
219
- return this.code === "BELOW_STRIPE_MINIMUM";
254
+ return this.code === "BELOW_CARD_MINIMUM" || this.rawCode === "BELOW_STRIPE_MINIMUM";
220
255
  }
221
256
  /** True if a Platform Commerce CARD purchase exceeded the hosted checkout's single-charge
222
257
  * cap of $999.99 (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. */
@@ -246,10 +281,12 @@ var InvoError = class _InvoError extends Error {
246
281
  function errorFromResponse(status, body, requestId) {
247
282
  let message = `INVO request failed (HTTP ${status})`;
248
283
  let code;
284
+ let rawCode;
249
285
  if (body && typeof body === "object") {
250
286
  const b = body;
251
- if (typeof b["code"] === "string") code = b["code"];
252
- else if (typeof b["error_code"] === "string") code = b["error_code"];
287
+ if (typeof b["code"] === "string") rawCode = b["code"];
288
+ else if (typeof b["error_code"] === "string") rawCode = b["error_code"];
289
+ code = typeof b["error_code_public"] === "string" ? b["error_code_public"] : rawCode;
253
290
  if (typeof b["error"] === "string") message = b["error"];
254
291
  else if (typeof b["message"] === "string") message = b["message"];
255
292
  if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited|service_unavailable)$/.test(
@@ -261,7 +298,7 @@ function errorFromResponse(status, body, requestId) {
261
298
  } else if (typeof body === "string" && body.trim()) {
262
299
  message = body;
263
300
  }
264
- return new InvoError({ message, code, status, body, requestId });
301
+ return new InvoError({ message, code, rawCode, status, body, requestId });
265
302
  }
266
303
 
267
304
  // src/shared/http.ts
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DjY-50jn.cjs';
2
- export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DjY-50jn.cjs';
1
+ import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DzmukUr9.cjs';
2
+ export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DzmukUr9.cjs';
3
3
 
4
4
  declare class PlatformCommerceClient {
5
5
  /**
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DjY-50jn.js';
2
- export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DjY-50jn.js';
1
+ import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DzmukUr9.js';
2
+ export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DzmukUr9.js';
3
3
 
4
4
  declare class PlatformCommerceClient {
5
5
  /**
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-BPZJ63RM.js';
2
- export { InvoError } from './chunk-BPZJ63RM.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-ZLPMCR5Q.js';
2
+ export { InvoError } from './chunk-ZLPMCR5Q.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {
package/dist/server.cjs CHANGED
@@ -8,6 +8,7 @@ var InvoError = class _InvoError extends Error {
8
8
  super(args.message);
9
9
  this.name = "InvoError";
10
10
  this.code = args.code;
11
+ this.rawCode = args.rawCode ?? args.code;
11
12
  this.status = args.status;
12
13
  this.body = args.body ?? null;
13
14
  this.requestId = args.requestId;
@@ -215,10 +216,44 @@ var InvoError = class _InvoError extends Error {
215
216
  get isAmountBelowMinimum() {
216
217
  return this.code === "AMOUNT_BELOW_MINIMUM";
217
218
  }
219
+ /**
220
+ * True if the `rail` you sent disagrees with the storefront key you
221
+ * authenticated with (`RAIL_CHANNEL_MISMATCH`, 400).
222
+ *
223
+ * A storefront key already determines the rail, so the fix is to stop sending
224
+ * `rail` — not to send a different one. The error body carries `channel` and
225
+ * `rail` so you can see which storefront the key belongs to.
226
+ *
227
+ * INVO refuses rather than silently overriding, because silently overriding
228
+ * would bill a player through a route you did not ask for.
229
+ */
230
+ get isRailChannelMismatch() {
231
+ return this.code === "RAIL_CHANNEL_MISMATCH";
232
+ }
233
+ /**
234
+ * True if a Steam purchase was attempted for a title INVO has not registered
235
+ * as distributed on Steam (`STEAM_RAIL_NOT_ENTITLED`, 403).
236
+ *
237
+ * Holding a `steam` storefront key does not by itself register the title —
238
+ * only INVO can do that. This is not retryable; contact INVO.
239
+ */
240
+ get isSteamRailNotEntitled() {
241
+ return this.code === "STEAM_RAIL_NOT_ENTITLED";
242
+ }
243
+ /**
244
+ * True if a title distributed on Steam tried to sell currency on a non-Steam
245
+ * rail (`STEAM_PURCHASE_LAYER_REQUIRED`, 409).
246
+ *
247
+ * Currency for a Steam title must be bought through Steam. Use the dedicated
248
+ * Steam purchase flow. Not retryable on the same rail.
249
+ */
250
+ get isSteamPurchaseLayerRequired() {
251
+ return this.code === "STEAM_PURCHASE_LAYER_REQUIRED";
252
+ }
218
253
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
219
254
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
220
255
  get isBelowCardMinimum() {
221
- return this.code === "BELOW_STRIPE_MINIMUM";
256
+ return this.code === "BELOW_CARD_MINIMUM" || this.rawCode === "BELOW_STRIPE_MINIMUM";
222
257
  }
223
258
  /** True if a Platform Commerce CARD purchase exceeded the hosted checkout's single-charge
224
259
  * cap of $999.99 (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. */
@@ -248,10 +283,12 @@ var InvoError = class _InvoError extends Error {
248
283
  function errorFromResponse(status, body, requestId) {
249
284
  let message = `INVO request failed (HTTP ${status})`;
250
285
  let code;
286
+ let rawCode;
251
287
  if (body && typeof body === "object") {
252
288
  const b = body;
253
- if (typeof b["code"] === "string") code = b["code"];
254
- else if (typeof b["error_code"] === "string") code = b["error_code"];
289
+ if (typeof b["code"] === "string") rawCode = b["code"];
290
+ else if (typeof b["error_code"] === "string") rawCode = b["error_code"];
291
+ code = typeof b["error_code_public"] === "string" ? b["error_code_public"] : rawCode;
255
292
  if (typeof b["error"] === "string") message = b["error"];
256
293
  else if (typeof b["message"] === "string") message = b["message"];
257
294
  if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited|service_unavailable)$/.test(
@@ -263,7 +300,7 @@ function errorFromResponse(status, body, requestId) {
263
300
  } else if (typeof body === "string" && body.trim()) {
264
301
  message = body;
265
302
  }
266
- return new InvoError({ message, code, status, body, requestId });
303
+ return new InvoError({ message, code, rawCode, status, body, requestId });
267
304
  }
268
305
 
269
306
  // src/shared/http.ts
@@ -1019,7 +1056,9 @@ var PlatformCommerceServer = class {
1019
1056
  amountUnit: raw["amount_unit"] ?? (fundingSource === "card" ? "usd" : void 0),
1020
1057
  // Balance leg: the canonical post-refund balance. Card leg: the processor's refund id.
1021
1058
  newBalance: raw["new_balance"] ?? null,
1022
- processorRefundId: raw["stripe_refund_id"],
1059
+ // Neutral field first — the backend emits `processor_refund_reference`
1060
+ // alongside the vendor-named one for exactly this reason.
1061
+ processorRefundId: raw["processor_refund_reference"] ?? raw["stripe_refund_id"],
1023
1062
  feeRetained: raw["fee_retained"] === true,
1024
1063
  raw
1025
1064
  };
@@ -1215,7 +1254,7 @@ var InvoServer = class {
1215
1254
  raw
1216
1255
  };
1217
1256
  }
1218
- /** Complete the Stripe-rail 3-D Secure step after the client finished card action. */
1257
+ /** Complete the card-rail 3-D Secure step after the client finished card action. */
1219
1258
  async confirmPayment(input, opts) {
1220
1259
  const body = { payment_intent_id: input.paymentIntentId };
1221
1260
  if (input.orderId) body["order_id"] = input.orderId;
package/dist/server.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, b as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as PurchaseItemInput, N as PurchaseItemResult, Q as ItemHistoryQuery, T as ItemHistoryResult, U as ItemOrderQuery, W as PlayerBalanceQuery, X as PlayerBalanceResult, Y as InboundPendingQuery, Z as InboundPendingResult, _ as LinkedIdentitiesQuery, $ as LinkedIdentitiesResult, a0 as SmsVerifyResult, a1 as ClaimTransferInput, a2 as ClaimResult, a3 as ClaimCurrencyInput, a4 as TransactionStatusResult, a5 as GuardianApprovalStatusResult, a6 as ServerDestinationsQuery, d as DestinationsResult, a7 as PhoneShareContact, a8 as PhoneShareInitiateResult, a9 as PhoneShareApproveInput, aa as PhoneShareApproveResult, ab as PhoneShareStatusResult } from './types-DjY-50jn.cjs';
2
- export { ac as CurrencyBalance, h as DestinationGame, ad as FundingSource, ae as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, af as LinkedIdentityEmail, ag as PlatformPurchaseStatus, n as Rail, V as VerificationMethod } from './types-DjY-50jn.cjs';
1
+ import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, b as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as PurchaseItemInput, N as PurchaseItemResult, Q as ItemHistoryQuery, T as ItemHistoryResult, U as ItemOrderQuery, W as PlayerBalanceQuery, X as PlayerBalanceResult, Y as InboundPendingQuery, Z as InboundPendingResult, _ as LinkedIdentitiesQuery, $ as LinkedIdentitiesResult, a0 as SmsVerifyResult, a1 as ClaimTransferInput, a2 as ClaimResult, a3 as ClaimCurrencyInput, a4 as TransactionStatusResult, a5 as GuardianApprovalStatusResult, a6 as ServerDestinationsQuery, d as DestinationsResult, a7 as PhoneShareContact, a8 as PhoneShareInitiateResult, a9 as PhoneShareApproveInput, aa as PhoneShareApproveResult, ab as PhoneShareStatusResult } from './types-DzmukUr9.cjs';
2
+ export { ac as CurrencyBalance, h as DestinationGame, ad as FundingSource, ae as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, af as LinkedIdentityEmail, ag as PlatformPurchaseStatus, n as Rail, V as VerificationMethod } from './types-DzmukUr9.cjs';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -248,6 +248,32 @@ declare class PlatformCommerceServer {
248
248
  */
249
249
  refund(input: PlatformRefundInput, opts?: CallOptions): Promise<PlatformRefundResult>;
250
250
  }
251
+ /**
252
+ * ## Storefront keys — one client per storefront
253
+ *
254
+ * A game that ships on more than one storefront (Steam, iOS, Android, web,
255
+ * console) has one SDK key per storefront. Construct one `InvoServer` per key
256
+ * and use whichever matches where the player is buying:
257
+ *
258
+ * ```ts
259
+ * const invo = {
260
+ * ios: new InvoServer({ gameSecret: process.env.INVO_KEY_IOS! }),
261
+ * android: new InvoServer({ gameSecret: process.env.INVO_KEY_ANDROID! }),
262
+ * web: new InvoServer({ gameSecret: process.env.INVO_KEY_WEB! }),
263
+ * };
264
+ * await invo[player.storefront].purchaseCurrency({ ... });
265
+ * ```
266
+ *
267
+ * **Do not pass `rail` when using a storefront key.** The key already
268
+ * determines it, and a conflicting `rail` is refused with
269
+ * `RAIL_CHANNEL_MISMATCH` rather than silently overridden — see
270
+ * {@link InvoError.isRailChannelMismatch}. A single legacy key with no
271
+ * storefront keeps working exactly as before, `rail` included.
272
+ *
273
+ * These are still **server-side** keys. A storefront key names where the
274
+ * purchase came from, not where the key lives; it never belongs in a game
275
+ * client, an app bundle, or browser code.
276
+ */
251
277
  declare class InvoServer {
252
278
  private readonly http;
253
279
  private readonly auth;
@@ -302,7 +328,7 @@ declare class InvoServer {
302
328
  * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
303
329
  */
304
330
  purchaseCurrency(input: PurchaseInput, opts?: CallOptions): Promise<PurchaseResult>;
305
- /** Complete the Stripe-rail 3-D Secure step after the client finished card action. */
331
+ /** Complete the card-rail 3-D Secure step after the client finished card action. */
306
332
  confirmPayment(input: {
307
333
  paymentIntentId: string;
308
334
  orderId?: string;
package/dist/server.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, b as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as PurchaseItemInput, N as PurchaseItemResult, Q as ItemHistoryQuery, T as ItemHistoryResult, U as ItemOrderQuery, W as PlayerBalanceQuery, X as PlayerBalanceResult, Y as InboundPendingQuery, Z as InboundPendingResult, _ as LinkedIdentitiesQuery, $ as LinkedIdentitiesResult, a0 as SmsVerifyResult, a1 as ClaimTransferInput, a2 as ClaimResult, a3 as ClaimCurrencyInput, a4 as TransactionStatusResult, a5 as GuardianApprovalStatusResult, a6 as ServerDestinationsQuery, d as DestinationsResult, a7 as PhoneShareContact, a8 as PhoneShareInitiateResult, a9 as PhoneShareApproveInput, aa as PhoneShareApproveResult, ab as PhoneShareStatusResult } from './types-DjY-50jn.js';
2
- export { ac as CurrencyBalance, h as DestinationGame, ad as FundingSource, ae as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, af as LinkedIdentityEmail, ag as PlatformPurchaseStatus, n as Rail, V as VerificationMethod } from './types-DjY-50jn.js';
1
+ import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, b as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as PurchaseItemInput, N as PurchaseItemResult, Q as ItemHistoryQuery, T as ItemHistoryResult, U as ItemOrderQuery, W as PlayerBalanceQuery, X as PlayerBalanceResult, Y as InboundPendingQuery, Z as InboundPendingResult, _ as LinkedIdentitiesQuery, $ as LinkedIdentitiesResult, a0 as SmsVerifyResult, a1 as ClaimTransferInput, a2 as ClaimResult, a3 as ClaimCurrencyInput, a4 as TransactionStatusResult, a5 as GuardianApprovalStatusResult, a6 as ServerDestinationsQuery, d as DestinationsResult, a7 as PhoneShareContact, a8 as PhoneShareInitiateResult, a9 as PhoneShareApproveInput, aa as PhoneShareApproveResult, ab as PhoneShareStatusResult } from './types-DzmukUr9.js';
2
+ export { ac as CurrencyBalance, h as DestinationGame, ad as FundingSource, ae as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, af as LinkedIdentityEmail, ag as PlatformPurchaseStatus, n as Rail, V as VerificationMethod } from './types-DzmukUr9.js';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -248,6 +248,32 @@ declare class PlatformCommerceServer {
248
248
  */
249
249
  refund(input: PlatformRefundInput, opts?: CallOptions): Promise<PlatformRefundResult>;
250
250
  }
251
+ /**
252
+ * ## Storefront keys — one client per storefront
253
+ *
254
+ * A game that ships on more than one storefront (Steam, iOS, Android, web,
255
+ * console) has one SDK key per storefront. Construct one `InvoServer` per key
256
+ * and use whichever matches where the player is buying:
257
+ *
258
+ * ```ts
259
+ * const invo = {
260
+ * ios: new InvoServer({ gameSecret: process.env.INVO_KEY_IOS! }),
261
+ * android: new InvoServer({ gameSecret: process.env.INVO_KEY_ANDROID! }),
262
+ * web: new InvoServer({ gameSecret: process.env.INVO_KEY_WEB! }),
263
+ * };
264
+ * await invo[player.storefront].purchaseCurrency({ ... });
265
+ * ```
266
+ *
267
+ * **Do not pass `rail` when using a storefront key.** The key already
268
+ * determines it, and a conflicting `rail` is refused with
269
+ * `RAIL_CHANNEL_MISMATCH` rather than silently overridden — see
270
+ * {@link InvoError.isRailChannelMismatch}. A single legacy key with no
271
+ * storefront keeps working exactly as before, `rail` included.
272
+ *
273
+ * These are still **server-side** keys. A storefront key names where the
274
+ * purchase came from, not where the key lives; it never belongs in a game
275
+ * client, an app bundle, or browser code.
276
+ */
251
277
  declare class InvoServer {
252
278
  private readonly http;
253
279
  private readonly auth;
@@ -302,7 +328,7 @@ declare class InvoServer {
302
328
  * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
303
329
  */
304
330
  purchaseCurrency(input: PurchaseInput, opts?: CallOptions): Promise<PurchaseResult>;
305
- /** Complete the Stripe-rail 3-D Secure step after the client finished card action. */
331
+ /** Complete the card-rail 3-D Secure step after the client finished card action. */
306
332
  confirmPayment(input: {
307
333
  paymentIntentId: string;
308
334
  orderId?: string;
package/dist/server.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-BPZJ63RM.js';
2
- export { InvoError } from './chunk-BPZJ63RM.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-ZLPMCR5Q.js';
2
+ export { InvoError } from './chunk-ZLPMCR5Q.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  var DEFAULT_TOLERANCE_SEC = 300;
@@ -512,7 +512,9 @@ var PlatformCommerceServer = class {
512
512
  amountUnit: raw["amount_unit"] ?? (fundingSource === "card" ? "usd" : void 0),
513
513
  // Balance leg: the canonical post-refund balance. Card leg: the processor's refund id.
514
514
  newBalance: raw["new_balance"] ?? null,
515
- processorRefundId: raw["stripe_refund_id"],
515
+ // Neutral field first — the backend emits `processor_refund_reference`
516
+ // alongside the vendor-named one for exactly this reason.
517
+ processorRefundId: raw["processor_refund_reference"] ?? raw["stripe_refund_id"],
516
518
  feeRetained: raw["fee_retained"] === true,
517
519
  raw
518
520
  };
@@ -708,7 +710,7 @@ var InvoServer = class {
708
710
  raw
709
711
  };
710
712
  }
711
- /** Complete the Stripe-rail 3-D Secure step after the client finished card action. */
713
+ /** Complete the card-rail 3-D Secure step after the client finished card action. */
712
714
  async confirmPayment(input, opts) {
713
715
  const body = { payment_intent_id: input.paymentIntentId };
714
716
  if (input.orderId) body["order_id"] = input.orderId;
@@ -7,8 +7,25 @@
7
7
  * `code` when present, else fall back to `message`. See the handoff doc §8.
8
8
  */
9
9
  declare class InvoError extends Error {
10
- /** Stable machine code from the backend (`code`), when present. */
10
+ /**
11
+ * Stable machine code, provider-neutral.
12
+ *
13
+ * When the backend stamps a neutral alias (`error_code_public`) — which it
14
+ * does for every code carrying a payment processor's name — this is that
15
+ * alias. Otherwise it is the wire code unchanged. Branch on this: it is the
16
+ * value INVO's public documentation prints, and it will not change under you
17
+ * if a processor does.
18
+ */
11
19
  readonly code: string | undefined;
20
+ /**
21
+ * The literal machine code on the wire, before any neutral aliasing.
22
+ *
23
+ * Equal to {@link code} for the overwhelming majority of errors. It differs
24
+ * only where the raw code names a processor. Provided so an integration that
25
+ * was already matching a raw value keeps a way to do so — but prefer
26
+ * {@link code} or the typed predicates below.
27
+ */
28
+ readonly rawCode: string | undefined;
12
29
  /** HTTP status. */
13
30
  readonly status: number;
14
31
  /** Raw parsed body, for debugging / fields not surfaced here. */
@@ -18,6 +35,7 @@ declare class InvoError extends Error {
18
35
  constructor(args: {
19
36
  message: string;
20
37
  code?: string;
38
+ rawCode?: string;
21
39
  status: number;
22
40
  body?: unknown;
23
41
  requestId?: string;
@@ -166,6 +184,34 @@ declare class InvoError extends Error {
166
184
  /** True if a Platform Commerce purchase was too small for the fee to round above zero
167
185
  * (`AMOUNT_BELOW_MINIMUM`, 400) — raise the amount. */
168
186
  get isAmountBelowMinimum(): boolean;
187
+ /**
188
+ * True if the `rail` you sent disagrees with the storefront key you
189
+ * authenticated with (`RAIL_CHANNEL_MISMATCH`, 400).
190
+ *
191
+ * A storefront key already determines the rail, so the fix is to stop sending
192
+ * `rail` — not to send a different one. The error body carries `channel` and
193
+ * `rail` so you can see which storefront the key belongs to.
194
+ *
195
+ * INVO refuses rather than silently overriding, because silently overriding
196
+ * would bill a player through a route you did not ask for.
197
+ */
198
+ get isRailChannelMismatch(): boolean;
199
+ /**
200
+ * True if a Steam purchase was attempted for a title INVO has not registered
201
+ * as distributed on Steam (`STEAM_RAIL_NOT_ENTITLED`, 403).
202
+ *
203
+ * Holding a `steam` storefront key does not by itself register the title —
204
+ * only INVO can do that. This is not retryable; contact INVO.
205
+ */
206
+ get isSteamRailNotEntitled(): boolean;
207
+ /**
208
+ * True if a title distributed on Steam tried to sell currency on a non-Steam
209
+ * rail (`STEAM_PURCHASE_LAYER_REQUIRED`, 409).
210
+ *
211
+ * Currency for a Steam title must be bought through Steam. Use the dedicated
212
+ * Steam purchase flow. Not retryable on the same rail.
213
+ */
214
+ get isSteamPurchaseLayerRequired(): boolean;
169
215
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
170
216
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
171
217
  get isBelowCardMinimum(): boolean;
@@ -7,8 +7,25 @@
7
7
  * `code` when present, else fall back to `message`. See the handoff doc §8.
8
8
  */
9
9
  declare class InvoError extends Error {
10
- /** Stable machine code from the backend (`code`), when present. */
10
+ /**
11
+ * Stable machine code, provider-neutral.
12
+ *
13
+ * When the backend stamps a neutral alias (`error_code_public`) — which it
14
+ * does for every code carrying a payment processor's name — this is that
15
+ * alias. Otherwise it is the wire code unchanged. Branch on this: it is the
16
+ * value INVO's public documentation prints, and it will not change under you
17
+ * if a processor does.
18
+ */
11
19
  readonly code: string | undefined;
20
+ /**
21
+ * The literal machine code on the wire, before any neutral aliasing.
22
+ *
23
+ * Equal to {@link code} for the overwhelming majority of errors. It differs
24
+ * only where the raw code names a processor. Provided so an integration that
25
+ * was already matching a raw value keeps a way to do so — but prefer
26
+ * {@link code} or the typed predicates below.
27
+ */
28
+ readonly rawCode: string | undefined;
12
29
  /** HTTP status. */
13
30
  readonly status: number;
14
31
  /** Raw parsed body, for debugging / fields not surfaced here. */
@@ -18,6 +35,7 @@ declare class InvoError extends Error {
18
35
  constructor(args: {
19
36
  message: string;
20
37
  code?: string;
38
+ rawCode?: string;
21
39
  status: number;
22
40
  body?: unknown;
23
41
  requestId?: string;
@@ -166,6 +184,34 @@ declare class InvoError extends Error {
166
184
  /** True if a Platform Commerce purchase was too small for the fee to round above zero
167
185
  * (`AMOUNT_BELOW_MINIMUM`, 400) — raise the amount. */
168
186
  get isAmountBelowMinimum(): boolean;
187
+ /**
188
+ * True if the `rail` you sent disagrees with the storefront key you
189
+ * authenticated with (`RAIL_CHANNEL_MISMATCH`, 400).
190
+ *
191
+ * A storefront key already determines the rail, so the fix is to stop sending
192
+ * `rail` — not to send a different one. The error body carries `channel` and
193
+ * `rail` so you can see which storefront the key belongs to.
194
+ *
195
+ * INVO refuses rather than silently overriding, because silently overriding
196
+ * would bill a player through a route you did not ask for.
197
+ */
198
+ get isRailChannelMismatch(): boolean;
199
+ /**
200
+ * True if a Steam purchase was attempted for a title INVO has not registered
201
+ * as distributed on Steam (`STEAM_RAIL_NOT_ENTITLED`, 403).
202
+ *
203
+ * Holding a `steam` storefront key does not by itself register the title —
204
+ * only INVO can do that. This is not retryable; contact INVO.
205
+ */
206
+ get isSteamRailNotEntitled(): boolean;
207
+ /**
208
+ * True if a title distributed on Steam tried to sell currency on a non-Steam
209
+ * rail (`STEAM_PURCHASE_LAYER_REQUIRED`, 409).
210
+ *
211
+ * Currency for a Steam title must be bought through Steam. Use the dedicated
212
+ * Steam purchase flow. Not retryable on the same rail.
213
+ */
214
+ get isSteamPurchaseLayerRequired(): boolean;
169
215
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
170
216
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
171
217
  get isBelowCardMinimum(): boolean;