@invonetwork/web-sdk 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ 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).
 
+## [1.2.0] — 2026-07-01
+
+Two more server-side capabilities on `InvoServer`.
+
+- **Phone-share OTP handshake** — `phoneShareInitiate` / `phoneShareApprove` / `phoneShareStatus`
+  resolve a `409 PHONE_SHARE_APPROVAL_REQUIRED`. Unauthenticated (phone-owner-driven — no game
+  secret, no player token), relayed by a partner backend; after approve, re-issue the identical
+  original request (the grant is server-side + auto-consumed). Adds
+  `InvoError.isPhoneShareAlreadyApproved`.
+- **Server-side `getDestinations`** — game-secret variant of the browser
+  `InvoClient.getDestinations`; pass `{ sourceGameId, direction }` (default `"transfer"`), rows
+  share the same `DestinationGame` shape.
+
+## [1.1.0] — 2026-07-01
+
+Four additive server-side flows on `InvoServer` (the SMS-PIN / claim-code / status /
+guardian paths partners still need alongside the passkey path).
+
+- **SMS-PIN completion** — `verifySmsTransfer` / `verifySmsSend` (for `verificationMethod: "sms"`).
+- **Claim-by-code** — `claimTransfer` / `claimCurrency`, incl. the `needsAccountSelection`
+  multi-account disambiguation (a `200` with `candidates`, not an error).
+- **Status reads** — `getTransferStatus` / `getSendStatus` (surface `verificationState`).
+- **Guardian approval-status poll** — `getGuardianApprovalStatus` (poll a hold to `state`).
+- New typed results (`SmsVerifyResult`, `ClaimResult`, `TransactionStatusResult`,
+  `GuardianApprovalStatusResult`) + `InvoError.isPhoneShareApprovalRequired`.
+
 ## [1.0.0] — 2026-07-01
 
 **1.0 — stable.** The public API is now covered by a stability commitment: it follows

package/README.md

@@ -179,7 +179,7 @@ const { checkoutUrl, sessionId, expiresAt } = await server.createCheckout({
   rail: "platform",                    // optional: "platform" (default) | "game" | "steam"
   successUrl: "https://you/buy/ok",
   cancelUrl: "https://you/buy/cancel",
-  metadata: { yourOrderId: "ord_42" }, // echoed on the purchase.completed webhook
+  metadata: { yourOrderId: "ord_42" }, // echoed on the purchase.completed webhook (all rails); order_id also reconciles
 });
 // → send the browser to checkoutUrl (single-use, ~15 min)
 ```
@@ -225,7 +225,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
+  metadata: { yourOrderId: "ord_42" },    // echoed on the purchase.completed webhook (all rails); order_id also reconciles
 });
 // purchase.status:
 //   "success"          → captured, purchase.newBalance updated
@@ -444,7 +444,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, metadata`) — `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` |
+| `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` (all rails); `order_id` is also on every webhook as a secondary reconciliation key (`getOrderDetails`). |
 | `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`) |
@@ -495,6 +495,8 @@ Helpers:
 | `.retryAfter` | seconds to back off on a 429 throttle |
 | `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
 | `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
+| `.isPhoneShareApprovalRequired` | a new-account phone needs owner approval → run the `phoneShare*` handshake, then retry |
+| `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
 
 Client-side guards (bad amount, missing idempotency key, `rail:"steam"` on `purchaseCurrency`, item validation) throw `InvoError` with `.status === 0` **before** any network call. Notable backend codes: `SDK_TOKEN_EXPIRED`, `TENANT_NOT_MIGRATED`, `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, `WEBAUTHN_UV_REQUIRED`, `ENROLLMENT_REQUIRES_PROOF`, `WRONG_RAIL_ENDPOINT`, `flow_paused`.
 
@@ -530,6 +532,12 @@ try {
 | `getPlayerBalance({ playerEmail? \| playerId? })` | `{ player, balances, summary, raw }` |
 | `getInboundPending({ playerEmail? \| playerPhone? })` | `{ inboundPending, raw }` — live unclaimed inbound sends/transfers |
 | `getLinkedIdentities({ playerEmail? \| playerPhone? })` | `{ walletUserId, primaryEmail, primaryPhone, isMinor, emails, notFound, raw }` — **server-only** (returns PII) |
+| `verifySmsTransfer(txnId, smsPin)` / `verifySmsSend(txnId, smsPin)` | `SmsVerifyResult` — complete the SMS-PIN path when `verificationMethod: "sms"` |
+| `claimTransfer(input)` / `claimCurrency(input)` | `ClaimResult` — redeem a claim code (`needsAccountSelection` + `candidates` on a multi-account phone) |
+| `getTransferStatus(txnId)` / `getSendStatus(txnId)` | `TransactionStatusResult` — poll outbound state (`verificationState`) |
+| `getGuardianApprovalStatus(txnId)` | `GuardianApprovalStatusResult` — poll a guardian hold to resolution (`state`) |
+| `getDestinations({ sourceGameId, direction? })` | `DestinationsResult` — server-side (game-secret) destinations; same rows as the browser variant |
+| `phoneShareInitiate({ phone, email })` / `phoneShareApprove({ approvalId, otp })` / `phoneShareStatus({ phone, email })` | phone-share OTP handshake (unauthenticated) to resolve a `PHONE_SHARE_APPROVAL_REQUIRED` (409); then re-issue the original request |
 | `iterateItemPurchaseHistory({ playerEmail, pageSize? })` | async iterator over all history rows |
 | `verifyWebhook(rawBody, signatureHeader, secret \| secrets, opts?)` | typed `InvoWebhookEvent` (throws on bad signature) |
 | `verifyWebhookAsync(...)` | same as `verifyWebhook`, Web Crypto (edge/Workers/Deno/Bun) |

package/dist/{chunk-D3XBTH4C.js → chunk-P65XQ6VF.js}

@@ -36,6 +36,14 @@ var InvoError = class _InvoError extends Error {
     const b = this.bodyObject();
     return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
   }
+  /** True if a claim needs phone-share approval before it can complete (claim → 409). */
+  get isPhoneShareApprovalRequired() {
+    return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
+  }
+  /** True if the phone-share (phone, requesting_email) pair was already approved. */
+  get isPhoneShareAlreadyApproved() {
+    return this.code === "PHONE_SHARE_ALREADY_APPROVED";
+  }
   /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
   get isDuplicateRequest() {
     return this.code === "DUPLICATE_REQUEST" || this.status === 409 && /duplicate/i.test(this.message);
@@ -256,6 +264,49 @@ function retryAfterMs(parsed, headers) {
   return void 0;
 }
 
-export { Http, InvoError, assertSecureBaseUrl };
-//# sourceMappingURL=chunk-D3XBTH4C.js.map
-//# sourceMappingURL=chunk-D3XBTH4C.js.map
+// src/shared/destinations.ts
+function toDestinationGame(row) {
+  const s = (k) => row[k] === void 0 || row[k] === null ? void 0 : String(row[k]);
+  return {
+    gameId: row["game_id"] ?? "",
+    gameName: String(row["game_name"] ?? ""),
+    tenantType: s("tenant_type"),
+    developerName: s("developer_name"),
+    publisherName: s("publisher_name"),
+    genre: s("genre"),
+    platform: s("platform"),
+    gameStatus: s("game_status"),
+    gameIcon: s("game_icon"),
+    gamePoster: s("game_poster"),
+    gameUrl: s("game_url"),
+    gameDescription: s("game_description"),
+    currencyName: String(row["currency_name"] ?? ""),
+    currencySymbol: String(row["currency_symbol"] ?? ""),
+    currencySymbolUrl: s("currency_symbol_url"),
+    minimumTransfer: String(row["minimum_transfer"] ?? ""),
+    maximumTransfer: String(row["maximum_transfer"] ?? ""),
+    raw: row
+  };
+}
+function toDestinationsResult(raw, direction) {
+  const games = Array.isArray(raw["available_games"]) ? raw["available_games"] : [];
+  return {
+    status: String(raw["status"] ?? ""),
+    sourceGameId: raw["source_game_id"] ?? "",
+    sourceGameName: String(raw["source_game_name"] ?? ""),
+    sourceGameIcon: raw["source_game_icon"],
+    sourceCurrencyName: String(raw["source_currency_name"] ?? ""),
+    sourceCurrencyIcon: raw["source_currency_icon"],
+    universalTransfers: raw["universal_transfers"] === true,
+    transferMode: String(raw["transfer_mode"] ?? ""),
+    availableGames: games.map(toDestinationGame),
+    totalDestinations: Number(raw["total_destinations"] ?? games.length),
+    direction: String(raw["direction"] ?? direction),
+    linkedGameIds: Array.isArray(raw["linked_game_ids"]) ? raw["linked_game_ids"] : void 0,
+    raw
+  };
+}
+
+export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
+//# sourceMappingURL=chunk-P65XQ6VF.js.map
+//# sourceMappingURL=chunk-P65XQ6VF.js.map

package/dist/index.cjs

@@ -38,6 +38,14 @@ var InvoError = class _InvoError extends Error {
     const b = this.bodyObject();
     return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
   }
+  /** True if a claim needs phone-share approval before it can complete (claim → 409). */
+  get isPhoneShareApprovalRequired() {
+    return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
+  }
+  /** True if the phone-share (phone, requesting_email) pair was already approved. */
+  get isPhoneShareAlreadyApproved() {
+    return this.code === "PHONE_SHARE_ALREADY_APPROVED";
+  }
   /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
   get isDuplicateRequest() {
     return this.code === "DUPLICATE_REQUEST" || this.status === 409 && /duplicate/i.test(this.message);
@@ -339,6 +347,49 @@ function assertionToJSON(cred) {
   };
 }
 
+// src/shared/destinations.ts
+function toDestinationGame(row) {
+  const s = (k) => row[k] === void 0 || row[k] === null ? void 0 : String(row[k]);
+  return {
+    gameId: row["game_id"] ?? "",
+    gameName: String(row["game_name"] ?? ""),
+    tenantType: s("tenant_type"),
+    developerName: s("developer_name"),
+    publisherName: s("publisher_name"),
+    genre: s("genre"),
+    platform: s("platform"),
+    gameStatus: s("game_status"),
+    gameIcon: s("game_icon"),
+    gamePoster: s("game_poster"),
+    gameUrl: s("game_url"),
+    gameDescription: s("game_description"),
+    currencyName: String(row["currency_name"] ?? ""),
+    currencySymbol: String(row["currency_symbol"] ?? ""),
+    currencySymbolUrl: s("currency_symbol_url"),
+    minimumTransfer: String(row["minimum_transfer"] ?? ""),
+    maximumTransfer: String(row["maximum_transfer"] ?? ""),
+    raw: row
+  };
+}
+function toDestinationsResult(raw, direction) {
+  const games = Array.isArray(raw["available_games"]) ? raw["available_games"] : [];
+  return {
+    status: String(raw["status"] ?? ""),
+    sourceGameId: raw["source_game_id"] ?? "",
+    sourceGameName: String(raw["source_game_name"] ?? ""),
+    sourceGameIcon: raw["source_game_icon"],
+    sourceCurrencyName: String(raw["source_currency_name"] ?? ""),
+    sourceCurrencyIcon: raw["source_currency_icon"],
+    universalTransfers: raw["universal_transfers"] === true,
+    transferMode: String(raw["transfer_mode"] ?? ""),
+    availableGames: games.map(toDestinationGame),
+    totalDestinations: Number(raw["total_destinations"] ?? games.length),
+    direction: String(raw["direction"] ?? direction),
+    linkedGameIds: Array.isArray(raw["linked_game_ids"]) ? raw["linked_game_ids"] : void 0,
+    raw
+  };
+}
+
 // src/index.ts
 function toPendingCollectItem(row) {
   return {
@@ -367,29 +418,6 @@ function toBalanceRow(row) {
     raw: row
   };
 }
-function toDestinationGame(row) {
-  const s = (k) => row[k] === void 0 || row[k] === null ? void 0 : String(row[k]);
-  return {
-    gameId: row["game_id"] ?? "",
-    gameName: String(row["game_name"] ?? ""),
-    tenantType: s("tenant_type"),
-    developerName: s("developer_name"),
-    publisherName: s("publisher_name"),
-    genre: s("genre"),
-    platform: s("platform"),
-    gameStatus: s("game_status"),
-    gameIcon: s("game_icon"),
-    gamePoster: s("game_poster"),
-    gameUrl: s("game_url"),
-    gameDescription: s("game_description"),
-    currencyName: String(row["currency_name"] ?? ""),
-    currencySymbol: String(row["currency_symbol"] ?? ""),
-    currencySymbolUrl: s("currency_symbol_url"),
-    minimumTransfer: String(row["minimum_transfer"] ?? ""),
-    maximumTransfer: String(row["maximum_transfer"] ?? ""),
-    raw: row
-  };
-}
 var InvoClient = class {
   constructor(config) {
     if (!config.token) throw new Error("InvoClient requires a player `token`.");
@@ -510,22 +538,7 @@ var InvoClient = class {
         `/api/sdk/destinations?direction=${encodeURIComponent(direction)}`,
         opts?.signal
       );
-      const games = Array.isArray(raw["available_games"]) ? raw["available_games"] : [];
-      return {
-        status: String(raw["status"] ?? ""),
-        sourceGameId: raw["source_game_id"] ?? "",
-        sourceGameName: String(raw["source_game_name"] ?? ""),
-        sourceGameIcon: raw["source_game_icon"],
-        sourceCurrencyName: String(raw["source_currency_name"] ?? ""),
-        sourceCurrencyIcon: raw["source_currency_icon"],
-        universalTransfers: raw["universal_transfers"] === true,
-        transferMode: String(raw["transfer_mode"] ?? ""),
-        availableGames: games.map(toDestinationGame),
-        totalDestinations: Number(raw["total_destinations"] ?? games.length),
-        direction: String(raw["direction"] ?? direction),
-        linkedGameIds: Array.isArray(raw["linked_game_ids"]) ? raw["linked_game_ids"] : void 0,
-        raw
-      };
+      return toDestinationsResult(raw, direction);
     });
   }
   /**

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, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult } from './types-DLSCxpoT.cjs';
-export { e as BalanceRow, f as DestinationGame, I as InvoError, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, k as PendingCollectItem, R as Rail, V as VerificationMethod } from './types-DLSCxpoT.cjs';
+import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult } from './types-DTAmriOB.cjs';
+export { e as BalanceRow, f as DestinationGame, I as InvoError, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, k as PendingCollectItem, R as Rail, V as VerificationMethod } from './types-DTAmriOB.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, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult } from './types-DLSCxpoT.js';
-export { e as BalanceRow, f as DestinationGame, I as InvoError, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, k as PendingCollectItem, R as Rail, V as VerificationMethod } from './types-DLSCxpoT.js';
+import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult } from './types-DTAmriOB.js';
+export { e as BalanceRow, f as DestinationGame, I as InvoError, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, k as PendingCollectItem, R as Rail, V as VerificationMethod } from './types-DTAmriOB.js';
 
 declare class InvoClient {
     private readonly http;

package/dist/index.js

@@ -1,5 +1,5 @@
-import { assertSecureBaseUrl, Http, InvoError } from './chunk-D3XBTH4C.js';
-export { InvoError } from './chunk-D3XBTH4C.js';
+import { assertSecureBaseUrl, Http, toDestinationsResult, InvoError } from './chunk-P65XQ6VF.js';
+export { InvoError } from './chunk-P65XQ6VF.js';
 
 // src/shared/webauthn.ts
 function b64urlToBuffer(value) {
@@ -110,29 +110,6 @@ function toBalanceRow(row) {
     raw: row
   };
 }
-function toDestinationGame(row) {
-  const s = (k) => row[k] === void 0 || row[k] === null ? void 0 : String(row[k]);
-  return {
-    gameId: row["game_id"] ?? "",
-    gameName: String(row["game_name"] ?? ""),
-    tenantType: s("tenant_type"),
-    developerName: s("developer_name"),
-    publisherName: s("publisher_name"),
-    genre: s("genre"),
-    platform: s("platform"),
-    gameStatus: s("game_status"),
-    gameIcon: s("game_icon"),
-    gamePoster: s("game_poster"),
-    gameUrl: s("game_url"),
-    gameDescription: s("game_description"),
-    currencyName: String(row["currency_name"] ?? ""),
-    currencySymbol: String(row["currency_symbol"] ?? ""),
-    currencySymbolUrl: s("currency_symbol_url"),
-    minimumTransfer: String(row["minimum_transfer"] ?? ""),
-    maximumTransfer: String(row["maximum_transfer"] ?? ""),
-    raw: row
-  };
-}
 var InvoClient = class {
   constructor(config) {
     if (!config.token) throw new Error("InvoClient requires a player `token`.");
@@ -253,22 +230,7 @@ var InvoClient = class {
         `/api/sdk/destinations?direction=${encodeURIComponent(direction)}`,
         opts?.signal
       );
-      const games = Array.isArray(raw["available_games"]) ? raw["available_games"] : [];
-      return {
-        status: String(raw["status"] ?? ""),
-        sourceGameId: raw["source_game_id"] ?? "",
-        sourceGameName: String(raw["source_game_name"] ?? ""),
-        sourceGameIcon: raw["source_game_icon"],
-        sourceCurrencyName: String(raw["source_currency_name"] ?? ""),
-        sourceCurrencyIcon: raw["source_currency_icon"],
-        universalTransfers: raw["universal_transfers"] === true,
-        transferMode: String(raw["transfer_mode"] ?? ""),
-        availableGames: games.map(toDestinationGame),
-        totalDestinations: Number(raw["total_destinations"] ?? games.length),
-        direction: String(raw["direction"] ?? direction),
-        linkedGameIds: Array.isArray(raw["linked_game_ids"]) ? raw["linked_game_ids"] : void 0,
-        raw
-      };
+      return toDestinationsResult(raw, direction);
     });
   }
   /**