@invonetwork/web-sdk 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to `@invonetwork/web-sdk` are documented here. This project
 [Semantic Versioning](https://semver.org/). Releases are managed with
 [changesets](https://github.com/changesets/changesets).
 
+## [0.5.0] — 2026-07-01
+
+Support partner `metadata` end-to-end on the purchase flow (additive, backward-compatible).
+
+- **`PurchaseCompletedData.metadata?`** — the `purchase.completed` webhook now echoes your
+  metadata back (all rails); `event.data.metadata` is typed.
+- **`purchaseCurrency`** now accepts and forwards `metadata` (the direct `/purchase-currency`
+  endpoint accepts it too, matching `createCheckout`).
+
+## [0.4.2] — 2026-06-30
+
+Fixes from an independent line-by-line audit against the live backend.
+
+- **`linkDevice` now works.** `device/link/webauthn/begin` returns a wrapped
+  `{ link_id, options }` body (challenge nested under `options`) and binds the
+  challenge to a server-generated `link_id`. The client now unwraps `options` and
+  echoes the server's `link_id` to `/complete` (it previously threw on an undefined
+  challenge and sent the wrong id).
+- **`InvoError.code` is now populated for the direct purchase rail + guardian flows.**
+  `errorFromResponse` reads `error_code` (SecureErrorHandler + `/purchase-currency`)
+  in addition to `code`, and promotes known no-code tokens (`flow_paused`,
+  `spending_limit_exceeded`, `receiver_not_enrolled_use_claim_code`) to `.code`. Fixes
+  `isDuplicateRequest` on the direct rail.
+- **Guardian/minor routing.** The 202 guardian body also carries
+  `verification_method:"sms"`; the SDK now suppresses it (reports
+  `verificationMethod: undefined`) so a guardian-pending minor isn't routed into the
+  SMS-PIN UI. README example reordered to branch on `guardianApproval` first.
+
 ## [0.4.1] — 2026-06-30
 
 Docs only — replaced the README's internal-leaking "Deployment prerequisites"

package/README.md

@@ -183,6 +183,7 @@ const purchase = await server.purchaseCurrency({
   purchaseReference: crypto.randomUUID(), // idempotency key, required
   rail: "platform",
   paymentMethodId: "pm_...",              // a tokenized payment method
+  metadata: { yourOrderId: "ord_42" },    // echoed back on the purchase.completed webhook
 });
 // purchase.status:
 //   "success"          → captured, purchase.newBalance updated
@@ -260,10 +261,11 @@ const t = await server.initiateTransfer({
 });
 // (initiateSend uses sender*/receiver* + receivingGameId instead)
 
+// Check guardianApproval FIRST — the guardian path takes precedence.
 switch (true) {
+  case !!t.guardianApproval:                  // minor/guardian path (HTTP 202) → pending approval, no PIN UI
   case t.verificationMethod === "in_app":     // sender is passkey-enrolled → approve in the browser
   case t.verificationMethod === "sms":        // not enrolled, a PIN was sent → show a PIN-entry fallback
-  case !!t.guardianApproval:                  // minor/guardian path (HTTP 202) → do NOT show the PIN UI
 }
 
 // 2. BROWSER — the sender approves with their passkey (give them t.transactionId + the player token)
@@ -280,7 +282,7 @@ try {
 }
 ```
 
-- **`verificationMethod`** (from initiate): `"in_app"` → passkey approve; `"sms"` → un-enrolled, PIN sent; `undefined` + `guardianApproval` → minor/guardian (HTTP 202), do **not** show the PIN UI.
+- **`verificationMethod`** (from initiate): `"in_app"` → passkey approve; `"sms"` → un-enrolled, PIN sent; `undefined` + `guardianApproval` → minor/guardian (HTTP 202), do **not** show the PIN UI. On the guardian path the SDK reports `verificationMethod: undefined` (even though the raw 202 body also carries `"sms"`) so `guardianApproval` wins — but branch on it first to be safe.
 - **Claim codes** are returned only by `approveTransfer`; they're the out-of-band fallback when the recipient isn't enrolled.
 - **`err.isReceiverNotEnrolled`** on `confirmReceipt*` is the explicit signal to switch to claim-code entry.
 - Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
@@ -368,7 +370,7 @@ export const POST = createWebhookHandler({
 
 | Event | Fires for | Use it to |
 |---|---|---|
-| `purchase.completed` | every currency-purchase rail | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail`) |
+| `purchase.completed` | every currency-purchase rail | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail, metadata`) — `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` |
 | `purchase.failed` / `purchase.disputed` | `platform` rail only | handle failures/disputes |
 | `purchase.refunded` | `game` / `steam` rails | handle refunds |
 | `item.purchased` | every item purchase | **grant the in-game item** (payload includes `transaction_id, order_id, player_email, identity_id, item_id, item_name, item_quantity, unit_price, total_price, currency_name, new_balance, fee_breakdown`) |

package/dist/{chunk-EEWOAUXO.js → chunk-JOVATUDY.js}

@@ -50,8 +50,12 @@ function errorFromResponse(status, body, requestId) {
   if (body && typeof body === "object") {
     const b = body;
     if (typeof b["code"] === "string") code = b["code"];
+    else if (typeof b["error_code"] === "string") code = b["error_code"];
     if (typeof b["error"] === "string") message = b["error"];
     else if (typeof b["message"] === "string") message = b["message"];
+    if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code)$/.test(b["error"])) {
+      code = b["error"];
+    }
   } else if (typeof body === "string" && body.trim()) {
     message = body;
   }
@@ -245,5 +249,5 @@ function retryAfterMs(parsed, headers) {
 }
 
 export { Http, InvoError, assertSecureBaseUrl };
-//# sourceMappingURL=chunk-EEWOAUXO.js.map
-//# sourceMappingURL=chunk-EEWOAUXO.js.map
+//# sourceMappingURL=chunk-JOVATUDY.js.map
+//# sourceMappingURL=chunk-JOVATUDY.js.map

package/dist/index.cjs

@@ -52,8 +52,12 @@ function errorFromResponse(status, body, requestId) {
   if (body && typeof body === "object") {
     const b = body;
     if (typeof b["code"] === "string") code = b["code"];
+    else if (typeof b["error_code"] === "string") code = b["error_code"];
     if (typeof b["error"] === "string") message = b["error"];
     else if (typeof b["message"] === "string") message = b["message"];
+    if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code)$/.test(b["error"])) {
+      code = b["error"];
+    }
   } else if (typeof body === "string" && body.trim()) {
     message = body;
   }
@@ -399,16 +403,22 @@ var InvoClient = class {
    */
   async linkDevice(linkId, opts) {
     if (!linkId) throw new Error("linkDevice requires a `linkId`.");
+    this.assertWebAuthn();
     const signal = opts?.signal;
     return this.withTokenRetry(async () => {
-      const assertion = await this.runAssertion(
+      const begin = await this.post(
         "/api/sdk/device/link/webauthn/begin",
         { link_id: linkId },
         signal
       );
+      const cred = await navigator.credentials.get({
+        publicKey: toRequestOptions(begin.options),
+        signal
+      });
+      if (!cred) throw new Error("Passkey assertion was cancelled or returned no credential.");
       const raw = await this.post(
         "/api/sdk/device/link/webauthn/complete",
-        { link_id: linkId, webauthn_assertion: assertion },
+        { link_id: begin.link_id, webauthn_assertion: assertionToJSON(cred) },
         signal
       );
       return { status: String(raw["status"] ?? ""), raw };

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult } from './types-CBMLNwbe.cjs';
-export { I as InvoError, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CBMLNwbe.cjs';
+import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult } from './types-CZdmipNK.cjs';
+export { I as InvoError, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CZdmipNK.cjs';
 
 declare class InvoClient {
     private readonly http;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult } from './types-CBMLNwbe.js';
-export { I as InvoError, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CBMLNwbe.js';
+import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult } from './types-CZdmipNK.js';
+export { I as InvoError, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CZdmipNK.js';
 
 declare class InvoClient {
     private readonly http;

package/dist/index.js

@@ -1,5 +1,5 @@
-import { assertSecureBaseUrl, Http, InvoError } from './chunk-EEWOAUXO.js';
-export { InvoError } from './chunk-EEWOAUXO.js';
+import { assertSecureBaseUrl, Http, InvoError } from './chunk-JOVATUDY.js';
+export { InvoError } from './chunk-JOVATUDY.js';
 
 // src/shared/webauthn.ts
 function b64urlToBuffer(value) {
@@ -154,16 +154,22 @@ var InvoClient = class {
    */
   async linkDevice(linkId, opts) {
     if (!linkId) throw new Error("linkDevice requires a `linkId`.");
+    this.assertWebAuthn();
     const signal = opts?.signal;
     return this.withTokenRetry(async () => {
-      const assertion = await this.runAssertion(
+      const begin = await this.post(
         "/api/sdk/device/link/webauthn/begin",
         { link_id: linkId },
         signal
       );
+      const cred = await navigator.credentials.get({
+        publicKey: toRequestOptions(begin.options),
+        signal
+      });
+      if (!cred) throw new Error("Passkey assertion was cancelled or returned no credential.");
       const raw = await this.post(
         "/api/sdk/device/link/webauthn/complete",
-        { link_id: linkId, webauthn_assertion: assertion },
+        { link_id: begin.link_id, webauthn_assertion: assertionToJSON(cred) },
         signal
       );
       return { status: String(raw["status"] ?? ""), raw };

package/dist/server.cjs

@@ -54,8 +54,12 @@ function errorFromResponse(status, body, requestId) {
   if (body && typeof body === "object") {
     const b = body;
     if (typeof b["code"] === "string") code = b["code"];
+    else if (typeof b["error_code"] === "string") code = b["error_code"];
     if (typeof b["error"] === "string") message = b["error"];
     else if (typeof b["message"] === "string") message = b["message"];
+    if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code)$/.test(b["error"])) {
+      code = b["error"];
+    }
   } else if (typeof body === "string" && body.trim()) {
     message = body;
   }
@@ -627,6 +631,7 @@ var InvoServer = class {
     if (input.savedCardId) body["saved_card_id"] = input.savedCardId;
     if (input.playerName) body["player_name"] = input.playerName;
     if (input.playerPhone) body["player_phone"] = input.playerPhone;
+    if (input.metadata) body["metadata"] = input.metadata;
     const raw = await this.http.post(
       "/api/currency-purchases/purchase-currency",
       body,
@@ -869,7 +874,7 @@ var InvoServer = class {
     const guardian = raw["guardian_approval"];
     return {
       transactionId: String(raw["transaction_id"] ?? ""),
-      verificationMethod: vm === "in_app" || vm === "sms" ? vm : void 0,
+      verificationMethod: guardian ? void 0 : vm === "in_app" || vm === "sms" ? vm : void 0,
       guardianApproval: guardian ?? void 0,
       raw
     };

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { I as InvoError, S as ServerConfig, a as CallOptions, P as PlayerToken, g as InitiateSendInput, h as InitiateResult, i as InitiateTransferInput, j as CreateCheckoutInput, k as CreateCheckoutResult, l as PurchaseInput, m as PurchaseResult, n as ConfirmPaymentResult, O as OrderDetailsResult, o as PurchaseItemInput, p as PurchaseItemResult, q as ItemHistoryQuery, r as ItemHistoryResult, s as ItemOrderQuery, t as PlayerBalanceQuery, u as PlayerBalanceResult, v as InboundPendingQuery, w as InboundPendingResult } from './types-CBMLNwbe.cjs';
-export { x as CurrencyBalance, y as InboundPendingItem, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CBMLNwbe.cjs';
+import { I as InvoError, S as ServerConfig, a as CallOptions, P as PlayerToken, g as InitiateSendInput, h as InitiateResult, i as InitiateTransferInput, j as CreateCheckoutInput, k as CreateCheckoutResult, l as PurchaseInput, m as PurchaseResult, n as ConfirmPaymentResult, O as OrderDetailsResult, o as PurchaseItemInput, p as PurchaseItemResult, q as ItemHistoryQuery, r as ItemHistoryResult, s as ItemOrderQuery, t as PlayerBalanceQuery, u as PlayerBalanceResult, v as InboundPendingQuery, w as InboundPendingResult } from './types-CZdmipNK.cjs';
+export { x as CurrencyBalance, y as InboundPendingItem, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CZdmipNK.cjs';
 
 interface VerifyWebhookOptions {
     /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -25,6 +25,8 @@ interface PurchaseCompletedData {
     currency_name: string;
     new_balance: string;
     rail: string;
+    /** The metadata you passed to createCheckout/purchaseCurrency, echoed back (all rails). */
+    metadata?: Record<string, unknown>;
     [key: string]: unknown;
 }
 interface PurchaseEventData {

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { I as InvoError, S as ServerConfig, a as CallOptions, P as PlayerToken, g as InitiateSendInput, h as InitiateResult, i as InitiateTransferInput, j as CreateCheckoutInput, k as CreateCheckoutResult, l as PurchaseInput, m as PurchaseResult, n as ConfirmPaymentResult, O as OrderDetailsResult, o as PurchaseItemInput, p as PurchaseItemResult, q as ItemHistoryQuery, r as ItemHistoryResult, s as ItemOrderQuery, t as PlayerBalanceQuery, u as PlayerBalanceResult, v as InboundPendingQuery, w as InboundPendingResult } from './types-CBMLNwbe.js';
-export { x as CurrencyBalance, y as InboundPendingItem, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CBMLNwbe.js';
+import { I as InvoError, S as ServerConfig, a as CallOptions, P as PlayerToken, g as InitiateSendInput, h as InitiateResult, i as InitiateTransferInput, j as CreateCheckoutInput, k as CreateCheckoutResult, l as PurchaseInput, m as PurchaseResult, n as ConfirmPaymentResult, O as OrderDetailsResult, o as PurchaseItemInput, p as PurchaseItemResult, q as ItemHistoryQuery, r as ItemHistoryResult, s as ItemOrderQuery, t as PlayerBalanceQuery, u as PlayerBalanceResult, v as InboundPendingQuery, w as InboundPendingResult } from './types-CZdmipNK.js';
+export { x as CurrencyBalance, y as InboundPendingItem, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CZdmipNK.js';
 
 interface VerifyWebhookOptions {
     /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -25,6 +25,8 @@ interface PurchaseCompletedData {
     currency_name: string;
     new_balance: string;
     rail: string;
+    /** The metadata you passed to createCheckout/purchaseCurrency, echoed back (all rails). */
+    metadata?: Record<string, unknown>;
     [key: string]: unknown;
 }
 interface PurchaseEventData {

package/dist/server.js

@@ -1,5 +1,5 @@
-import { InvoError, assertSecureBaseUrl, Http } from './chunk-EEWOAUXO.js';
-export { InvoError } from './chunk-EEWOAUXO.js';
+import { InvoError, assertSecureBaseUrl, Http } from './chunk-JOVATUDY.js';
+export { InvoError } from './chunk-JOVATUDY.js';
 import { createHmac } from 'crypto';
 
 var DEFAULT_TOLERANCE_SEC = 300;
@@ -382,6 +382,7 @@ var InvoServer = class {
     if (input.savedCardId) body["saved_card_id"] = input.savedCardId;
     if (input.playerName) body["player_name"] = input.playerName;
     if (input.playerPhone) body["player_phone"] = input.playerPhone;
+    if (input.metadata) body["metadata"] = input.metadata;
     const raw = await this.http.post(
       "/api/currency-purchases/purchase-currency",
       body,
@@ -624,7 +625,7 @@ var InvoServer = class {
     const guardian = raw["guardian_approval"];
     return {
       transactionId: String(raw["transaction_id"] ?? ""),
-      verificationMethod: vm === "in_app" || vm === "sms" ? vm : void 0,
+      verificationMethod: guardian ? void 0 : vm === "in_app" || vm === "sms" ? vm : void 0,
       guardianApproval: guardian ?? void 0,
       raw
     };

package/dist/{types-CBMLNwbe.d.cts → types-CZdmipNK.d.cts}

@@ -176,6 +176,8 @@ interface PurchaseInput {
     savedCardId?: string;
     playerName?: string;
     playerPhone?: string;
+    /** Arbitrary metadata echoed back on the purchase.completed webhook (data.metadata). */
+    metadata?: Record<string, unknown>;
 }
 type PurchaseStatus = "success" | "requires_action" | "pending_payment";
 interface PurchaseResult {

package/dist/{types-CBMLNwbe.d.ts → types-CZdmipNK.d.ts}

@@ -176,6 +176,8 @@ interface PurchaseInput {
     savedCardId?: string;
     playerName?: string;
     playerPhone?: string;
+    /** Arbitrary metadata echoed back on the purchase.completed webhook (data.metadata). */
+    metadata?: Record<string, unknown>;
 }
 type PurchaseStatus = "success" | "requires_action" | "pending_payment";
 interface PurchaseResult {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invonetwork/web-sdk",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
   "license": "SEE LICENSE IN LICENSE",
   "private": false,