@invonetwork/web-sdk 3.0.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.
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;
@@ -132,6 +133,67 @@ var InvoError = class _InvoError extends Error {
132
133
  get isNonSteamValueIntoSteamBlocked() {
133
134
  return this.code === "NON_STEAM_VALUE_INTO_STEAM_BLOCKED";
134
135
  }
136
+ /**
137
+ * True if the initiate was refused because **the caller's OWN game is in testing**
138
+ * (`SOURCE_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
139
+ * the backend uses the same code on its Amazon rewards-send path too (not wrapped here),
140
+ * so one branch keeps working if that flow is ever added.
141
+ *
142
+ * **The caller can self-serve this**: switch the game to Live in the developer console
143
+ * (Game Settings → Status). Show `err.message` — it names the game and the exact control.
144
+ * `err.gameStatus` carries the current state if you want to render it.
145
+ *
146
+ * Deliberately distinct from {@link isTargetGameNotLive} — do NOT collapse the two into
147
+ * one "not live" case. The remediation differs: this one the developer can fix, the
148
+ * other one they cannot.
149
+ */
150
+ get isSourceGameNotLive() {
151
+ return this.code === "SOURCE_GAME_NOT_LIVE";
152
+ }
153
+ /**
154
+ * True if the initiate was refused because **the DESTINATION game is in testing**
155
+ * (`TARGET_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
156
+ * same backend vocabulary on the Amazon rewards-send path (not wrapped here).
157
+ *
158
+ * **The caller usually CANNOT fix this** — the destination is another developer's game
159
+ * and only its owner can switch it to Live. Don't offer a "go fix it" action; show
160
+ * `err.message` and, ideally, steer the player to a different destination
161
+ * (`getDestinations`). `err.gameStatus` carries the current state.
162
+ *
163
+ * Deliberately distinct from {@link isSourceGameNotLive} — see the note there.
164
+ */
165
+ get isTargetGameNotLive() {
166
+ return this.code === "TARGET_GAME_NOT_LIVE";
167
+ }
168
+ /**
169
+ * The game's current status from a `*_GAME_NOT_LIVE` refusal (`game_status`, e.g.
170
+ * `"testing"`) — for rendering the actual state. Present on both the source and target
171
+ * refusals.
172
+ */
173
+ get gameStatus() {
174
+ const v = this.bodyObject()["game_status"];
175
+ return typeof v === "string" && v ? v : void 0;
176
+ }
177
+ /**
178
+ * True if the tenant has **no verified WebAuthn RP ID**, so passkey endpoints are dark
179
+ * (`WEBAUTHN_NOT_ENABLED_FOR_TENANT`, 403).
180
+ *
181
+ * **This is a configuration state, not a failure.** Passkey step-up is per-tenant and
182
+ * stays dark until the developer verifies a domain in the console. Treat it as
183
+ * "this tenant hasn't enabled passkeys yet" and fall back to the SMS/in-app path rather
184
+ * than surfacing an error to the player — the ceremony was never available to fail.
185
+ *
186
+ * This is currently the COMMON case, not an edge case: as of 2026-08-05 only 4 of 23
187
+ * sandbox tenants and **0 of 3 production tenants** have a verified RP ID. Every
188
+ * integration needs this branch until domain verification is widespread.
189
+ *
190
+ * The fix (for the developer's own tenant) is to verify a domain — see the passkey
191
+ * prerequisites in the README. Note this refusal carries the code on `code`, not
192
+ * `error_code`; the SDK reads both, so `err.code` is populated either way.
193
+ */
194
+ get isWebauthnNotEnabledForTenant() {
195
+ return this.code === "WEBAUTHN_NOT_ENABLED_FOR_TENANT";
196
+ }
135
197
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
136
198
  get isPhoneShareAlreadyApproved() {
137
199
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -154,10 +216,44 @@ var InvoError = class _InvoError extends Error {
154
216
  get isAmountBelowMinimum() {
155
217
  return this.code === "AMOUNT_BELOW_MINIMUM";
156
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
+ }
157
253
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
158
254
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
159
255
  get isBelowCardMinimum() {
160
- return this.code === "BELOW_STRIPE_MINIMUM";
256
+ return this.code === "BELOW_CARD_MINIMUM" || this.rawCode === "BELOW_STRIPE_MINIMUM";
161
257
  }
162
258
  /** True if a Platform Commerce CARD purchase exceeded the hosted checkout's single-charge
163
259
  * cap of $999.99 (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. */
@@ -187,10 +283,12 @@ var InvoError = class _InvoError extends Error {
187
283
  function errorFromResponse(status, body, requestId) {
188
284
  let message = `INVO request failed (HTTP ${status})`;
189
285
  let code;
286
+ let rawCode;
190
287
  if (body && typeof body === "object") {
191
288
  const b = body;
192
- if (typeof b["code"] === "string") code = b["code"];
193
- 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;
194
292
  if (typeof b["error"] === "string") message = b["error"];
195
293
  else if (typeof b["message"] === "string") message = b["message"];
196
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(
@@ -202,7 +300,7 @@ function errorFromResponse(status, body, requestId) {
202
300
  } else if (typeof body === "string" && body.trim()) {
203
301
  message = body;
204
302
  }
205
- return new InvoError({ message, code, status, body, requestId });
303
+ return new InvoError({ message, code, rawCode, status, body, requestId });
206
304
  }
207
305
 
208
306
  // src/shared/http.ts
@@ -958,7 +1056,9 @@ var PlatformCommerceServer = class {
958
1056
  amountUnit: raw["amount_unit"] ?? (fundingSource === "card" ? "usd" : void 0),
959
1057
  // Balance leg: the canonical post-refund balance. Card leg: the processor's refund id.
960
1058
  newBalance: raw["new_balance"] ?? null,
961
- 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"],
962
1062
  feeRetained: raw["fee_retained"] === true,
963
1063
  raw
964
1064
  };
@@ -1154,7 +1254,7 @@ var InvoServer = class {
1154
1254
  raw
1155
1255
  };
1156
1256
  }
1157
- /** 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. */
1158
1258
  async confirmPayment(input, opts) {
1159
1259
  const body = { payment_intent_id: input.paymentIntentId };
1160
1260
  if (input.orderId) body["order_id"] = input.orderId;
@@ -1428,10 +1528,22 @@ var InvoServer = class {
1428
1528
  };
1429
1529
  }
1430
1530
  /**
1431
- * Complete a TRANSFER's SMS-PIN step (un-enrolled fallback). NOT idempotent —
1432
- * each attempt is counted server-side, so this is never auto-retried. A bad PIN
1433
- * throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a blocked
1434
- * recipient throws 429 (`sms_verification_blocked`).
1531
+ * Complete a TRANSFER's SMS-PIN step — the LAST-RESORT fallback for a sender who has
1532
+ * no passkey.
1533
+ *
1534
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
1535
+ * remove this method. **Passkeys are the gold standard for authorizing money movement**
1536
+ * — an SMS PIN is a shared secret on a channel exposed to SIM swap and interception,
1537
+ * and it is not a peer of a WebAuthn assertion. When `initiate*` returns
1538
+ * `verificationMethod: "sms"` it is telling you the sender has no passkey: prompt
1539
+ * `InvoClient.enrollPasskey()` and then approve with
1540
+ * `InvoClient.approveTransfer(transactionId)`. Reach for this method only when the user
1541
+ * cannot enroll (unsupported device) or declines. Still fully functional — this
1542
+ * annotation changes documentation only, not behavior.
1543
+ *
1544
+ * NOT idempotent — each attempt is counted server-side, so this is never auto-retried.
1545
+ * A bad PIN throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a
1546
+ * blocked recipient throws 429 (`sms_verification_blocked`).
1435
1547
  */
1436
1548
  async verifySmsTransfer(transactionId, smsPin, opts) {
1437
1549
  if (typeof transactionId !== "string" || !transactionId.trim()) {
@@ -1449,7 +1561,15 @@ var InvoServer = class {
1449
1561
  );
1450
1562
  return toSmsVerifyResult(raw);
1451
1563
  }
1452
- /** Complete a SEND's SMS-PIN step (un-enrolled fallback). See verifySmsTransfer. */
1564
+ /**
1565
+ * Complete a SEND's SMS-PIN step — the LAST-RESORT fallback for a sender who has no
1566
+ * passkey. See {@link verifySmsTransfer}.
1567
+ *
1568
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
1569
+ * remove this method. Prompt `InvoClient.enrollPasskey()` and approve with
1570
+ * `InvoClient.approveSend(transactionId)` instead; use this only when the user cannot
1571
+ * enroll or declines. Documentation only — behavior is unchanged.
1572
+ */
1453
1573
  async verifySmsSend(transactionId, smsPin, opts) {
1454
1574
  if (typeof transactionId !== "string" || !transactionId.trim()) {
1455
1575
  throw invalidInput("transactionId", transactionId, "is required");
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-DMNXAGiw.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-DMNXAGiw.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;
@@ -365,13 +391,33 @@ declare class InvoServer {
365
391
  */
366
392
  getLinkedIdentities(query: LinkedIdentitiesQuery, opts?: CallOptions): Promise<LinkedIdentitiesResult>;
367
393
  /**
368
- * Complete a TRANSFER's SMS-PIN step (un-enrolled fallback). NOT idempotent —
369
- * each attempt is counted server-side, so this is never auto-retried. A bad PIN
370
- * throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a blocked
371
- * recipient throws 429 (`sms_verification_blocked`).
394
+ * Complete a TRANSFER's SMS-PIN step — the LAST-RESORT fallback for a sender who has
395
+ * no passkey.
396
+ *
397
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
398
+ * remove this method. **Passkeys are the gold standard for authorizing money movement**
399
+ * — an SMS PIN is a shared secret on a channel exposed to SIM swap and interception,
400
+ * and it is not a peer of a WebAuthn assertion. When `initiate*` returns
401
+ * `verificationMethod: "sms"` it is telling you the sender has no passkey: prompt
402
+ * `InvoClient.enrollPasskey()` and then approve with
403
+ * `InvoClient.approveTransfer(transactionId)`. Reach for this method only when the user
404
+ * cannot enroll (unsupported device) or declines. Still fully functional — this
405
+ * annotation changes documentation only, not behavior.
406
+ *
407
+ * NOT idempotent — each attempt is counted server-side, so this is never auto-retried.
408
+ * A bad PIN throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a
409
+ * blocked recipient throws 429 (`sms_verification_blocked`).
372
410
  */
373
411
  verifySmsTransfer(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
374
- /** Complete a SEND's SMS-PIN step (un-enrolled fallback). See verifySmsTransfer. */
412
+ /**
413
+ * Complete a SEND's SMS-PIN step — the LAST-RESORT fallback for a sender who has no
414
+ * passkey. See {@link verifySmsTransfer}.
415
+ *
416
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
417
+ * remove this method. Prompt `InvoClient.enrollPasskey()` and approve with
418
+ * `InvoClient.approveSend(transactionId)` instead; use this only when the user cannot
419
+ * enroll or declines. Documentation only — behavior is unchanged.
420
+ */
375
421
  verifySmsSend(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
376
422
  /**
377
423
  * Claim an inbound TRANSFER by its claim code, crediting one of this game's currencies.
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-DMNXAGiw.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-DMNXAGiw.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;
@@ -365,13 +391,33 @@ declare class InvoServer {
365
391
  */
366
392
  getLinkedIdentities(query: LinkedIdentitiesQuery, opts?: CallOptions): Promise<LinkedIdentitiesResult>;
367
393
  /**
368
- * Complete a TRANSFER's SMS-PIN step (un-enrolled fallback). NOT idempotent —
369
- * each attempt is counted server-side, so this is never auto-retried. A bad PIN
370
- * throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a blocked
371
- * recipient throws 429 (`sms_verification_blocked`).
394
+ * Complete a TRANSFER's SMS-PIN step — the LAST-RESORT fallback for a sender who has
395
+ * no passkey.
396
+ *
397
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
398
+ * remove this method. **Passkeys are the gold standard for authorizing money movement**
399
+ * — an SMS PIN is a shared secret on a channel exposed to SIM swap and interception,
400
+ * and it is not a peer of a WebAuthn assertion. When `initiate*` returns
401
+ * `verificationMethod: "sms"` it is telling you the sender has no passkey: prompt
402
+ * `InvoClient.enrollPasskey()` and then approve with
403
+ * `InvoClient.approveTransfer(transactionId)`. Reach for this method only when the user
404
+ * cannot enroll (unsupported device) or declines. Still fully functional — this
405
+ * annotation changes documentation only, not behavior.
406
+ *
407
+ * NOT idempotent — each attempt is counted server-side, so this is never auto-retried.
408
+ * A bad PIN throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a
409
+ * blocked recipient throws 429 (`sms_verification_blocked`).
372
410
  */
373
411
  verifySmsTransfer(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
374
- /** Complete a SEND's SMS-PIN step (un-enrolled fallback). See verifySmsTransfer. */
412
+ /**
413
+ * Complete a SEND's SMS-PIN step — the LAST-RESORT fallback for a sender who has no
414
+ * passkey. See {@link verifySmsTransfer}.
415
+ *
416
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
417
+ * remove this method. Prompt `InvoClient.enrollPasskey()` and approve with
418
+ * `InvoClient.approveSend(transactionId)` instead; use this only when the user cannot
419
+ * enroll or declines. Documentation only — behavior is unchanged.
420
+ */
375
421
  verifySmsSend(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
376
422
  /**
377
423
  * Claim an inbound TRANSFER by its claim code, crediting one of this game's currencies.
package/dist/server.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-SPTYWJDN.js';
2
- export { InvoError } from './chunk-SPTYWJDN.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;
@@ -982,10 +984,22 @@ var InvoServer = class {
982
984
  };
983
985
  }
984
986
  /**
985
- * Complete a TRANSFER's SMS-PIN step (un-enrolled fallback). NOT idempotent —
986
- * each attempt is counted server-side, so this is never auto-retried. A bad PIN
987
- * throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a blocked
988
- * recipient throws 429 (`sms_verification_blocked`).
987
+ * Complete a TRANSFER's SMS-PIN step — the LAST-RESORT fallback for a sender who has
988
+ * no passkey.
989
+ *
990
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
991
+ * remove this method. **Passkeys are the gold standard for authorizing money movement**
992
+ * — an SMS PIN is a shared secret on a channel exposed to SIM swap and interception,
993
+ * and it is not a peer of a WebAuthn assertion. When `initiate*` returns
994
+ * `verificationMethod: "sms"` it is telling you the sender has no passkey: prompt
995
+ * `InvoClient.enrollPasskey()` and then approve with
996
+ * `InvoClient.approveTransfer(transactionId)`. Reach for this method only when the user
997
+ * cannot enroll (unsupported device) or declines. Still fully functional — this
998
+ * annotation changes documentation only, not behavior.
999
+ *
1000
+ * NOT idempotent — each attempt is counted server-side, so this is never auto-retried.
1001
+ * A bad PIN throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a
1002
+ * blocked recipient throws 429 (`sms_verification_blocked`).
989
1003
  */
990
1004
  async verifySmsTransfer(transactionId, smsPin, opts) {
991
1005
  if (typeof transactionId !== "string" || !transactionId.trim()) {
@@ -1003,7 +1017,15 @@ var InvoServer = class {
1003
1017
  );
1004
1018
  return toSmsVerifyResult(raw);
1005
1019
  }
1006
- /** Complete a SEND's SMS-PIN step (un-enrolled fallback). See verifySmsTransfer. */
1020
+ /**
1021
+ * Complete a SEND's SMS-PIN step — the LAST-RESORT fallback for a sender who has no
1022
+ * passkey. See {@link verifySmsTransfer}.
1023
+ *
1024
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
1025
+ * remove this method. Prompt `InvoClient.enrollPasskey()` and approve with
1026
+ * `InvoClient.approveSend(transactionId)` instead; use this only when the user cannot
1027
+ * enroll or declines. Documentation only — behavior is unchanged.
1028
+ */
1007
1029
  async verifySmsSend(transactionId, smsPin, opts) {
1008
1030
  if (typeof transactionId !== "string" || !transactionId.trim()) {
1009
1031
  throw invalidInput("transactionId", transactionId, "is required");
@@ -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;
@@ -100,6 +118,58 @@ declare class InvoError extends Error {
100
118
  * pick a non-Steam destination (surfaced via `DestinationGame.acceptsSteamOriginValue`).
101
119
  */
102
120
  get isNonSteamValueIntoSteamBlocked(): boolean;
121
+ /**
122
+ * True if the initiate was refused because **the caller's OWN game is in testing**
123
+ * (`SOURCE_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
124
+ * the backend uses the same code on its Amazon rewards-send path too (not wrapped here),
125
+ * so one branch keeps working if that flow is ever added.
126
+ *
127
+ * **The caller can self-serve this**: switch the game to Live in the developer console
128
+ * (Game Settings → Status). Show `err.message` — it names the game and the exact control.
129
+ * `err.gameStatus` carries the current state if you want to render it.
130
+ *
131
+ * Deliberately distinct from {@link isTargetGameNotLive} — do NOT collapse the two into
132
+ * one "not live" case. The remediation differs: this one the developer can fix, the
133
+ * other one they cannot.
134
+ */
135
+ get isSourceGameNotLive(): boolean;
136
+ /**
137
+ * True if the initiate was refused because **the DESTINATION game is in testing**
138
+ * (`TARGET_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
139
+ * same backend vocabulary on the Amazon rewards-send path (not wrapped here).
140
+ *
141
+ * **The caller usually CANNOT fix this** — the destination is another developer's game
142
+ * and only its owner can switch it to Live. Don't offer a "go fix it" action; show
143
+ * `err.message` and, ideally, steer the player to a different destination
144
+ * (`getDestinations`). `err.gameStatus` carries the current state.
145
+ *
146
+ * Deliberately distinct from {@link isSourceGameNotLive} — see the note there.
147
+ */
148
+ get isTargetGameNotLive(): boolean;
149
+ /**
150
+ * The game's current status from a `*_GAME_NOT_LIVE` refusal (`game_status`, e.g.
151
+ * `"testing"`) — for rendering the actual state. Present on both the source and target
152
+ * refusals.
153
+ */
154
+ get gameStatus(): string | undefined;
155
+ /**
156
+ * True if the tenant has **no verified WebAuthn RP ID**, so passkey endpoints are dark
157
+ * (`WEBAUTHN_NOT_ENABLED_FOR_TENANT`, 403).
158
+ *
159
+ * **This is a configuration state, not a failure.** Passkey step-up is per-tenant and
160
+ * stays dark until the developer verifies a domain in the console. Treat it as
161
+ * "this tenant hasn't enabled passkeys yet" and fall back to the SMS/in-app path rather
162
+ * than surfacing an error to the player — the ceremony was never available to fail.
163
+ *
164
+ * This is currently the COMMON case, not an edge case: as of 2026-08-05 only 4 of 23
165
+ * sandbox tenants and **0 of 3 production tenants** have a verified RP ID. Every
166
+ * integration needs this branch until domain verification is widespread.
167
+ *
168
+ * The fix (for the developer's own tenant) is to verify a domain — see the passkey
169
+ * prerequisites in the README. Note this refusal carries the code on `code`, not
170
+ * `error_code`; the SDK reads both, so `err.code` is populated either way.
171
+ */
172
+ get isWebauthnNotEnabledForTenant(): boolean;
103
173
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
104
174
  get isPhoneShareAlreadyApproved(): boolean;
105
175
  /** True if an idempotency-keyed request was a duplicate (item / platform purchase → 409). */
@@ -114,6 +184,34 @@ declare class InvoError extends Error {
114
184
  /** True if a Platform Commerce purchase was too small for the fee to round above zero
115
185
  * (`AMOUNT_BELOW_MINIMUM`, 400) — raise the amount. */
116
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;
117
215
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
118
216
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
119
217
  get isBelowCardMinimum(): boolean;
@@ -223,7 +321,14 @@ interface CallOptions {
223
321
  /** Public, neutral payment-rail names. Provider/processor names are an internal
224
322
  * backend routing detail and are deliberately NOT exposed here. */
225
323
  type Rail = "platform" | "game" | "steam";
226
- /** Verification method returned by initiate-send / initiate-transfer. */
324
+ /**
325
+ * Verification method returned by initiate-send / initiate-transfer.
326
+ *
327
+ * These are NOT two equivalent options. `"in_app"` is the passkey (WebAuthn) approve —
328
+ * the gold standard and the path to build for. `"sms"` means the sender has **no passkey
329
+ * enrolled** and the backend fell back to a PIN; treat it as a prompt to enroll, not as a
330
+ * destination. The SMS-PIN path is being phased out.
331
+ */
227
332
  type VerificationMethod = "in_app" | "sms";
228
333
  interface InvoConfig {
229
334
  /** API base URL. Prod: "https://invo.network". Sandbox: "https://sandbox.invo.network/sandbox". */
@@ -288,7 +393,11 @@ interface InitiateTransferInput {
288
393
  interface InitiateResult {
289
394
  transactionId: string;
290
395
  /**
291
- * "in_app" → proceed to the passkey approve flow; "sms" → un-enrolled fallback.
396
+ * `"in_app"` → the sender has a passkey; proceed to the approve flow (the recommended
397
+ * and only non-deprecated path). `"sms"` → the sender has **no passkey**, so a PIN was
398
+ * sent as a last-resort fallback — the best response is to offer `enrollPasskey()` and
399
+ * then `approveSend`/`approveTransfer`, falling back to the PIN pad only if they can't
400
+ * or won't enroll. The SMS-PIN completion is being phased out.
292
401
  * `undefined` when the backend returned the minor/guardian path (HTTP 202) and
293
402
  * no verification method applies yet — check `guardianApproval` and do NOT route
294
403
  * the user into the SMS-PIN UI in that case (§4.3 / §8).
@@ -752,6 +861,11 @@ interface LinkDeviceResult {
752
861
  status: string;
753
862
  raw: Record<string, unknown>;
754
863
  }
864
+ /**
865
+ * Result of `verifySmsTransfer` / `verifySmsSend` — the last-resort path for senders with
866
+ * no passkey. The SMS-PIN completion is being phased out; passkey approve
867
+ * (`InvoClient.approveSend` / `approveTransfer`) is the gold standard.
868
+ */
755
869
  interface SmsVerifyResult {
756
870
  /** "success" on a completed verification. */
757
871
  status: string;