@invonetwork/web-sdk 2.4.1 → 2.5.1

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
@@ -71,7 +71,9 @@ var InvoError = class _InvoError extends Error {
71
71
  get isInsufficientBalance() {
72
72
  if (this.status !== 400) return false;
73
73
  const b = this.bodyObject();
74
- return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
74
+ return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || // Zero-balance variant ("Player has no balance in this tenant") carries only
75
+ // `current_balance` — same top-up condition, so classify it the same way.
76
+ "current_balance" in b || /insufficient[_ ]balance/i.test(this.message);
75
77
  }
76
78
  /**
77
79
  * True if the call needs phone-share approval before it can complete (409) — the
@@ -134,10 +136,37 @@ var InvoError = class _InvoError extends Error {
134
136
  get isPhoneShareAlreadyApproved() {
135
137
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
136
138
  }
137
- /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
139
+ /** True if an idempotency-keyed request was a duplicate (item / platform purchase → 409). */
138
140
  get isDuplicateRequest() {
139
141
  return this.code === "DUPLICATE_REQUEST" || this.status === 409 && /duplicate/i.test(this.message);
140
142
  }
143
+ /**
144
+ * True if a Platform Commerce call was rejected because the tenant isn't a platform
145
+ * tenant (`NOT_A_PLATFORM_TENANT`, 403). Platform Commerce (`invo.platformCommerce.*`)
146
+ * is only for non-game platform tenants — a game tenant should use `purchaseItem`
147
+ * (spend game currency) or `createCheckout`/`purchaseCurrency` (buy currency) instead.
148
+ */
149
+ get isNotPlatformTenant() {
150
+ return this.code === "NOT_A_PLATFORM_TENANT";
151
+ }
152
+ /** True if a Platform Commerce purchase was too small for the fee to round above zero
153
+ * (`AMOUNT_BELOW_MINIMUM`, 400) — raise the amount. */
154
+ get isAmountBelowMinimum() {
155
+ return this.code === "AMOUNT_BELOW_MINIMUM";
156
+ }
157
+ /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
158
+ * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
159
+ get isBelowCardMinimum() {
160
+ return this.code === "BELOW_STRIPE_MINIMUM";
161
+ }
162
+ /**
163
+ * True if a Platform Commerce refund targeted an order that was already refunded
164
+ * (409). Idempotent outcome — the original refund did happen, so treat this as
165
+ * success, not a failure to retry-loop.
166
+ */
167
+ get isAlreadyRefunded() {
168
+ return this.code === "ALREADY_REFUNDED" || this.status === 409 && /already\s+refunded/i.test(this.message);
169
+ }
141
170
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
142
171
  get retryAfter() {
143
172
  const v = this.bodyObject()["retry_after"];
@@ -159,10 +188,11 @@ function errorFromResponse(status, body, requestId) {
159
188
  else if (typeof b["error_code"] === "string") code = b["error_code"];
160
189
  if (typeof b["error"] === "string") message = b["error"];
161
190
  else if (typeof b["message"] === "string") message = b["message"];
162
- if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited)$/.test(
191
+ 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(
163
192
  b["error"]
164
193
  )) {
165
194
  code = b["error"];
195
+ if (typeof b["message"] === "string" && b["message"]) message = b["message"];
166
196
  }
167
197
  } else if (typeof body === "string" && body.trim()) {
168
198
  message = body;
@@ -578,7 +608,7 @@ async function hmacHexSubtle(secret, message) {
578
608
  }
579
609
 
580
610
  // src/server.ts
581
- var DEFAULT_UA = "invonetwork-web-sdk/2.4.1 (+https://invo.network)";
611
+ var DEFAULT_UA = "invonetwork-web-sdk/2.5.1 (+https://invo.network)";
582
612
  var MAX_USD_AMOUNT = 999.99;
583
613
  var MAX_ITEM_PRICE = 999999.99;
584
614
  function invalidInput(label, value, why) {
@@ -739,6 +769,217 @@ function requireField(value, field, raw) {
739
769
  }
740
770
  return s;
741
771
  }
772
+ var FUNDING_SOURCES = /* @__PURE__ */ new Set(["balance", "card"]);
773
+ function invalidInputNoEcho(label, why) {
774
+ return new InvoError({ message: `${label} ${why}.`, code: "INVALID_INPUT", status: 0 });
775
+ }
776
+ function assertBillingAddress(addr, label) {
777
+ if (!addr || typeof addr !== "object") {
778
+ throw invalidInputNoEcho(label, 'is required for the "card" funding source and must be an object');
779
+ }
780
+ const required = [
781
+ [`${label}.line1`, addr.line1],
782
+ [`${label}.city`, addr.city],
783
+ [`${label}.postalCode`, addr.postalCode],
784
+ [`${label}.country`, addr.country]
785
+ ];
786
+ for (const [k, v] of required) {
787
+ if (typeof v !== "string" || !v.trim()) throw invalidInputNoEcho(k, "is required");
788
+ }
789
+ if (!/^[A-Za-z]{2}$/.test(addr.country)) {
790
+ throw invalidInputNoEcho(`${label}.country`, "must be a 2-letter ISO country code");
791
+ }
792
+ const optional = [
793
+ [`${label}.name`, addr.name],
794
+ [`${label}.line2`, addr.line2],
795
+ [`${label}.state`, addr.state]
796
+ ];
797
+ for (const [k, v] of optional) {
798
+ if (v !== void 0 && typeof v !== "string") {
799
+ throw invalidInputNoEcho(k, "must be a string when provided");
800
+ }
801
+ }
802
+ }
803
+ function toBillingAddressBody(addr) {
804
+ const body = {
805
+ line1: addr.line1,
806
+ city: addr.city,
807
+ postal_code: addr.postalCode,
808
+ country: addr.country
809
+ };
810
+ if (addr.name) body["name"] = addr.name;
811
+ if (addr.line2) body["line2"] = addr.line2;
812
+ if (addr.state) body["state"] = addr.state;
813
+ return body;
814
+ }
815
+ var PlatformCommerceServer = class {
816
+ constructor(http, auth) {
817
+ this.http = http;
818
+ this.auth = auth;
819
+ }
820
+ /**
821
+ * Create a purchase. The funding source is resolved server-side under lock — the client
822
+ * can request `"balance"` or `"card"`, but the backend verifies the real balance before
823
+ * value moves.
824
+ *
825
+ * - `fundingSource: "balance"` → settles synchronously; result `status:"success"` with
826
+ * `newBalance`/`financialBreakdown`. `totalPrice` is the tenant's network-currency amount.
827
+ * - `fundingSource: "card"` → result `status:"requires_payment"` + `clientSecret`; hand
828
+ * that to the browser `platformCommerce.confirmCardPayment`. `totalPrice` is USD and a
829
+ * `billingAddress` is REQUIRED. The sale is real only on the `platform_commerce.purchased`
830
+ * webhook — never on the client confirmation.
831
+ *
832
+ * Idempotent on `clientRequestId` (a duplicate throws a 409 `err.isDuplicateRequest`).
833
+ * A non-platform tenant throws `err.isNotPlatformTenant` (403).
834
+ *
835
+ * ⚠ Card-leg caveat: if the RESPONSE to a card purchase is lost (timeout after the
836
+ * backend created the order), re-sending the same `clientRequestId` returns the duplicate
837
+ * 409 and the `clientSecret` cannot be re-fetched — reconcile that order via the
838
+ * `platform_commerce.purchased` webhook / `getStatus`, and use a NEW `clientRequestId`
839
+ * for a fresh attempt. The balance leg has no such gap.
840
+ */
841
+ async purchase(input, opts) {
842
+ const required = [
843
+ ["clientRequestId", input.clientRequestId],
844
+ ["playerEmail", input.playerEmail],
845
+ ["playerName", input.playerName],
846
+ ["itemId", input.itemId],
847
+ ["itemName", input.itemName]
848
+ ];
849
+ for (const [k, v] of required) {
850
+ if (typeof v !== "string" || !v.trim()) throw invalidInput(k, v, "is required");
851
+ }
852
+ if (!FUNDING_SOURCES.has(input.fundingSource)) {
853
+ throw invalidInput("fundingSource", input.fundingSource, 'must be "balance" or "card"');
854
+ }
855
+ if (!Number.isInteger(input.itemQuantity) || input.itemQuantity < 1 || input.itemQuantity > 1e3) {
856
+ throw invalidInput("itemQuantity", input.itemQuantity, "must be an integer 1..1000");
857
+ }
858
+ const unit = parseMoney(input.unitPrice, MAX_ITEM_PRICE, "unitPrice");
859
+ const total = parseMoney(input.totalPrice, MAX_ITEM_PRICE, "totalPrice");
860
+ const expectedCents = Math.round(unit * input.itemQuantity * 100);
861
+ const totalCents = Math.round(total * 100);
862
+ if (Math.abs(totalCents - expectedCents) > 1) {
863
+ throw invalidInput(
864
+ "totalPrice",
865
+ input.totalPrice,
866
+ `must equal unitPrice \xD7 itemQuantity (\xB10.01): ${unit} \xD7 ${input.itemQuantity}`
867
+ );
868
+ }
869
+ if (input.fundingSource === "card") {
870
+ assertBillingAddress(input.billingAddress, "billingAddress");
871
+ }
872
+ if (input.playerPhone !== void 0) assertE164(input.playerPhone, "playerPhone");
873
+ const body = {
874
+ client_request_id: input.clientRequestId,
875
+ funding_source: input.fundingSource,
876
+ player_email: input.playerEmail,
877
+ player_name: input.playerName,
878
+ item_id: input.itemId,
879
+ item_name: input.itemName,
880
+ item_quantity: input.itemQuantity,
881
+ unit_price: input.unitPrice,
882
+ total_price: input.totalPrice
883
+ };
884
+ if (input.playerPhone) body["player_phone"] = input.playerPhone;
885
+ if (input.itemDescription) body["item_description"] = input.itemDescription;
886
+ if (input.itemCategory) body["item_category"] = input.itemCategory;
887
+ if (input.billingAddress) body["billing_address"] = toBillingAddressBody(input.billingAddress);
888
+ const raw = await this.http.post(
889
+ "/api/platform-commerce/purchase",
890
+ body,
891
+ this.auth,
892
+ { idempotent: true, signal: opts?.signal }
893
+ // client_request_id makes this safe to retry (dup → 409)
894
+ );
895
+ const orderIdRaw = raw["order_id"];
896
+ requireField(orderIdRaw, "order_id", raw);
897
+ const status = String(raw["status"] ?? "");
898
+ if (status === "requires_payment" && !raw["client_secret"]) {
899
+ requireField(raw["client_secret"], "client_secret", raw);
900
+ }
901
+ return {
902
+ status,
903
+ fundingSource: String(raw["funding_source"] ?? input.fundingSource),
904
+ orderId: orderIdRaw,
905
+ transactionId: raw["transaction_id"],
906
+ newBalance: raw["new_balance"] ?? null,
907
+ previousBalance: raw["previous_balance"] ?? null,
908
+ currencyName: raw["currency_name"],
909
+ financialBreakdown: raw["financial_breakdown"],
910
+ clientSecret: raw["client_secret"],
911
+ amountUsd: raw["amount_usd"] ?? null,
912
+ raw
913
+ };
914
+ }
915
+ /** Poll an order's status: `completed` (balance immediately; card after the webhook),
916
+ * `pending_payment` (card awaiting confirmation), or `refunded`. */
917
+ async getStatus(orderId, opts) {
918
+ if (orderId == null || String(orderId).trim() === "") {
919
+ throw invalidInput("orderId", orderId, "is required");
920
+ }
921
+ const raw = await this.http.get(
922
+ `/api/platform-commerce/purchase-status/${encodeURIComponent(String(orderId))}`,
923
+ this.auth,
924
+ { signal: opts?.signal }
925
+ );
926
+ return {
927
+ orderId: raw["order_id"] ?? orderId,
928
+ status: String(raw["status"] ?? ""),
929
+ gameCurrencyAmount: raw["game_currency_amount"] ?? null,
930
+ usdAmount: raw["usd_amount"] ?? null,
931
+ paymentMethod: raw["payment_method"],
932
+ createdAt: raw["created_at"],
933
+ raw
934
+ };
935
+ }
936
+ /**
937
+ * Refund a completed purchase. Provide EXACTLY ONE of `orderId` or `clientRequestId`.
938
+ * INVO retains its fee — the customer is made whole (balance re-credit or card refund)
939
+ * minus that fee. Idempotent on the order: a second refund throws a 409
940
+ * (`err.isAlreadyRefunded`) — treat that as "already done", not a failure.
941
+ */
942
+ async refund(input, opts) {
943
+ const hasOrder = input.orderId != null && String(input.orderId).trim() !== "";
944
+ const hasReq = typeof input.clientRequestId === "string" && input.clientRequestId.trim() !== "";
945
+ if (hasOrder === hasReq) {
946
+ throw new InvoError({
947
+ message: "refund requires EXACTLY ONE of orderId or clientRequestId.",
948
+ code: "INVALID_INPUT",
949
+ status: 0
950
+ });
951
+ }
952
+ const body = {};
953
+ if (hasOrder) body["order_id"] = input.orderId;
954
+ else body["client_request_id"] = input.clientRequestId;
955
+ if (input.reason) body["reason"] = input.reason;
956
+ const raw = await this.http.post(
957
+ "/api/platform-commerce/refund",
958
+ body,
959
+ this.auth,
960
+ // Idempotent on the order: a lost-response retry re-refunds nothing (backend 409s
961
+ // "already refunded"), so a transient 5xx/network retry is safe.
962
+ { idempotent: true, signal: opts?.signal }
963
+ );
964
+ const fundingSource = raw["funding_source"];
965
+ return {
966
+ status: String(raw["status"] ?? ""),
967
+ orderId: raw["order_id"] ?? void 0,
968
+ fundingSource,
969
+ transactionId: raw["transaction_id"],
970
+ // Backend key differs per leg: `refunded_amount` (balance) / `refunded_amount_usd` (card).
971
+ refundedAmount: raw["refunded_amount"] ?? raw["refunded_amount_usd"] ?? null,
972
+ // The refund HTTP response carries no unit; derive it (card → USD). The balance leg's
973
+ // unit is the tenant's network currency, not present here — left undefined.
974
+ amountUnit: raw["amount_unit"] ?? (fundingSource === "card" ? "usd" : void 0),
975
+ // Balance leg: the canonical post-refund balance. Card leg: the processor's refund id.
976
+ newBalance: raw["new_balance"] ?? null,
977
+ processorRefundId: raw["stripe_refund_id"],
978
+ feeRetained: raw["fee_retained"] === true,
979
+ raw
980
+ };
981
+ }
982
+ };
742
983
  var InvoServer = class {
743
984
  constructor(config) {
744
985
  if (!config.gameSecret) throw new Error("InvoServer requires a `gameSecret`.");
@@ -755,6 +996,7 @@ var InvoServer = class {
755
996
  hooks: config.hooks
756
997
  });
757
998
  this.auth = { kind: "game-secret", secret: config.gameSecret };
999
+ this.platformCommerce = new PlatformCommerceServer(this.http, this.auth);
758
1000
  }
759
1001
  /**
760
1002
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
@@ -1436,6 +1678,7 @@ var InvoServer = class {
1436
1678
 
1437
1679
  exports.InvoError = InvoError;
1438
1680
  exports.InvoServer = InvoServer;
1681
+ exports.PlatformCommerceServer = PlatformCommerceServer;
1439
1682
  exports.createWebhookHandler = createWebhookHandler;
1440
1683
  exports.verifyWebhook = verifyWebhook;
1441
1684
  exports.verifyWebhookAsync = verifyWebhookAsync;
package/dist/server.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, S as ServerConfig, a as CallOptions, n as PlayerToken, o as InitiateSendInput, p as InitiateResult, q as InitiateTransferInput, r as CreateCheckoutInput, s as CreateCheckoutResult, t as PurchaseInput, u as PurchaseResult, v as ConfirmPaymentResult, O as OrderDetailsResult, w as PurchaseItemInput, x as PurchaseItemResult, y as ItemHistoryQuery, z as ItemHistoryResult, F as ItemOrderQuery, G as PlayerBalanceQuery, H as PlayerBalanceResult, J as InboundPendingQuery, K as InboundPendingResult, M as LinkedIdentitiesQuery, N as LinkedIdentitiesResult, Q as SmsVerifyResult, T as ClaimTransferInput, U as ClaimResult, W as ClaimCurrencyInput, X as TransactionStatusResult, Y as GuardianApprovalStatusResult, Z as ServerDestinationsQuery, c as DestinationsResult, _ as PhoneShareContact, $ as PhoneShareInitiateResult, a0 as PhoneShareApproveInput, a1 as PhoneShareApproveResult, a2 as PhoneShareStatusResult } from './types-7Hl0Z1Ta.cjs';
2
- export { a3 as CurrencyBalance, g as DestinationGame, a4 as InboundPendingItem, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, a5 as LinkedIdentityEmail, m as Rail, V as VerificationMethod } from './types-7Hl0Z1Ta.cjs';
1
+ import { o as InvoError, H as Http, v as AuthHeader, w as PlatformPurchaseInput, d as CallOptions, x as PlatformPurchaseResult, y as PlatformOrderStatusResult, z as PlatformRefundInput, F as PlatformRefundResult, S as ServerConfig, G as PlayerToken, J as InitiateSendInput, K as InitiateResult, N as InitiateTransferInput, O as CreateCheckoutInput, Q as CreateCheckoutResult, T as PurchaseInput, U as PurchaseResult, W as ConfirmPaymentResult, X as OrderDetailsResult, Y as PurchaseItemInput, Z as PurchaseItemResult, _ as ItemHistoryQuery, $ as ItemHistoryResult, a0 as ItemOrderQuery, a1 as PlayerBalanceQuery, a2 as PlayerBalanceResult, a3 as InboundPendingQuery, a4 as InboundPendingResult, a5 as LinkedIdentitiesQuery, a6 as LinkedIdentitiesResult, a7 as SmsVerifyResult, a8 as ClaimTransferInput, a9 as ClaimResult, aa as ClaimCurrencyInput, ab as TransactionStatusResult, ac as GuardianApprovalStatusResult, ad as ServerDestinationsQuery, f as DestinationsResult, ae as PhoneShareContact, af as PhoneShareInitiateResult, ag as PhoneShareApproveInput, ah as PhoneShareApproveResult, ai as PhoneShareStatusResult } from './types-BHvVjdMV.cjs';
2
+ export { aj as BillingAddress, ak as CurrencyBalance, k as DestinationGame, al as FundingSource, am as InboundPendingItem, p as InvoErrorInfo, q as InvoHooks, r as InvoRequestInfo, s as InvoResponseInfo, an as LinkedIdentityEmail, ao as PlatformPurchaseStatus, u as Rail, V as VerificationMethod } from './types-BHvVjdMV.cjs';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -53,6 +53,47 @@ interface ItemPurchasedData {
53
53
  fee_breakdown?: Record<string, unknown>;
54
54
  [key: string]: unknown;
55
55
  }
56
+ /** `platform_commerce.purchased` — a Platform Commerce (ecommerce) purchase completed
57
+ * (balance immediately; card after the payment settles). Fulfill card orders on THIS,
58
+ * never on the browser confirmation. */
59
+ interface PlatformCommercePurchasedData {
60
+ transaction_id: string;
61
+ order_id: string | number;
62
+ /** "balance" | "card". */
63
+ funding_source: string;
64
+ player_email: string;
65
+ identity_id: string;
66
+ item_id: string;
67
+ item_name: string;
68
+ item_quantity: number;
69
+ /** Balance leg only — the network-currency amount. The CARD leg carries `total_price_usd`
70
+ * instead (this field is absent there). */
71
+ total_price?: string;
72
+ /** Balance leg only. */
73
+ unit_price?: string;
74
+ currency_name?: string;
75
+ new_balance?: string;
76
+ /** Card leg only (the USD charged). */
77
+ total_price_usd?: string;
78
+ fee_breakdown?: Record<string, unknown>;
79
+ [key: string]: unknown;
80
+ }
81
+ /** `platform_commerce.refunded` — a Platform Commerce purchase was refunded. INVO keeps
82
+ * its fee (`fee_retained: true`); the customer is made whole minus that fee. */
83
+ interface PlatformCommerceRefundedData {
84
+ order_id: string | number;
85
+ /** "balance" | "card". */
86
+ funding_source: string;
87
+ /** Null when the player row no longer exists at refund time. */
88
+ player_email: string | null;
89
+ /** Nullable for the same reason. */
90
+ identity_id?: string | null;
91
+ refunded_amount: string;
92
+ /** `"usd"` (card) or the literal `"currency"` (balance). */
93
+ amount_unit: string;
94
+ fee_retained: boolean;
95
+ [key: string]: unknown;
96
+ }
56
97
  interface TransferEventData {
57
98
  transaction_id: string;
58
99
  /** "transfer" | "send". */
@@ -79,6 +120,12 @@ type InvoWebhookEvent = (WebhookBase & {
79
120
  }) | (WebhookBase & {
80
121
  event_type: "item.purchased";
81
122
  data: ItemPurchasedData;
123
+ }) | (WebhookBase & {
124
+ event_type: "platform_commerce.purchased";
125
+ data: PlatformCommercePurchasedData;
126
+ }) | (WebhookBase & {
127
+ event_type: "platform_commerce.refunded";
128
+ data: PlatformCommerceRefundedData;
82
129
  }) | (WebhookBase & {
83
130
  event_type: PurchaseEventType;
84
131
  data: PurchaseEventData;
@@ -145,9 +192,71 @@ interface WebhookHandlerOptions {
145
192
  */
146
193
  declare function createWebhookHandler(opts: WebhookHandlerOptions): (request: Request) => Promise<Response>;
147
194
 
195
+ /**
196
+ * @invonetwork/web-sdk/server — NODE entry.
197
+ *
198
+ * InvoServer holds the game secret and runs every server-side call: minting the
199
+ * short-lived player token for the browser, initiating sends/transfers, and the
200
+ * currency-purchase flow (hosted checkout + rail selector). The game secret must
201
+ * NEVER reach the browser.
202
+ *
203
+ * All endpoints here authenticate with the `X-Game-Secret-Key` header.
204
+ */
205
+
206
+ /**
207
+ * Platform Commerce — the ECOMMERCE surface (server side). A PLATFORM tenant (a non-game
208
+ * app: vertical video, creator merch, marketplace) sells items funded by INVO balance OR a
209
+ * real card, with INVO as merchant of record and full refunds. This is NOT item purchase
210
+ * (§4.8) — that is a GAME tenant spending a player's existing game currency on an in-game
211
+ * item (balance only, no card, no refund). Different endpoints, different fee, different
212
+ * settlement. Reached as `invo.platformCommerce.*`.
213
+ */
214
+ declare class PlatformCommerceServer {
215
+ private readonly http;
216
+ private readonly auth;
217
+ constructor(http: Http, auth: AuthHeader);
218
+ /**
219
+ * Create a purchase. The funding source is resolved server-side under lock — the client
220
+ * can request `"balance"` or `"card"`, but the backend verifies the real balance before
221
+ * value moves.
222
+ *
223
+ * - `fundingSource: "balance"` → settles synchronously; result `status:"success"` with
224
+ * `newBalance`/`financialBreakdown`. `totalPrice` is the tenant's network-currency amount.
225
+ * - `fundingSource: "card"` → result `status:"requires_payment"` + `clientSecret`; hand
226
+ * that to the browser `platformCommerce.confirmCardPayment`. `totalPrice` is USD and a
227
+ * `billingAddress` is REQUIRED. The sale is real only on the `platform_commerce.purchased`
228
+ * webhook — never on the client confirmation.
229
+ *
230
+ * Idempotent on `clientRequestId` (a duplicate throws a 409 `err.isDuplicateRequest`).
231
+ * A non-platform tenant throws `err.isNotPlatformTenant` (403).
232
+ *
233
+ * ⚠ Card-leg caveat: if the RESPONSE to a card purchase is lost (timeout after the
234
+ * backend created the order), re-sending the same `clientRequestId` returns the duplicate
235
+ * 409 and the `clientSecret` cannot be re-fetched — reconcile that order via the
236
+ * `platform_commerce.purchased` webhook / `getStatus`, and use a NEW `clientRequestId`
237
+ * for a fresh attempt. The balance leg has no such gap.
238
+ */
239
+ purchase(input: PlatformPurchaseInput, opts?: CallOptions): Promise<PlatformPurchaseResult>;
240
+ /** Poll an order's status: `completed` (balance immediately; card after the webhook),
241
+ * `pending_payment` (card awaiting confirmation), or `refunded`. */
242
+ getStatus(orderId: string | number, opts?: CallOptions): Promise<PlatformOrderStatusResult>;
243
+ /**
244
+ * Refund a completed purchase. Provide EXACTLY ONE of `orderId` or `clientRequestId`.
245
+ * INVO retains its fee — the customer is made whole (balance re-credit or card refund)
246
+ * minus that fee. Idempotent on the order: a second refund throws a 409
247
+ * (`err.isAlreadyRefunded`) — treat that as "already done", not a failure.
248
+ */
249
+ refund(input: PlatformRefundInput, opts?: CallOptions): Promise<PlatformRefundResult>;
250
+ }
148
251
  declare class InvoServer {
149
252
  private readonly http;
150
253
  private readonly auth;
254
+ /**
255
+ * Platform Commerce (ecommerce) — a PLATFORM tenant selling items funded by balance or
256
+ * card, with refunds. DISTINCT from `purchaseItem` (a game tenant spending existing game
257
+ * currency on an in-game item). See {@link PlatformCommerceServer}.
258
+ */
259
+ readonly platformCommerce: PlatformCommerceServer;
151
260
  constructor(config: ServerConfig);
152
261
  /**
153
262
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
@@ -323,4 +432,4 @@ declare class InvoServer {
323
432
  private toInitiateResult;
324
433
  }
325
434
 
326
- export { CallOptions, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, DestinationsResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, ServerDestinationsQuery, SmsVerifyResult, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
435
+ export { CallOptions, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, DestinationsResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, ServerDestinationsQuery, SmsVerifyResult, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
package/dist/server.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, S as ServerConfig, a as CallOptions, n as PlayerToken, o as InitiateSendInput, p as InitiateResult, q as InitiateTransferInput, r as CreateCheckoutInput, s as CreateCheckoutResult, t as PurchaseInput, u as PurchaseResult, v as ConfirmPaymentResult, O as OrderDetailsResult, w as PurchaseItemInput, x as PurchaseItemResult, y as ItemHistoryQuery, z as ItemHistoryResult, F as ItemOrderQuery, G as PlayerBalanceQuery, H as PlayerBalanceResult, J as InboundPendingQuery, K as InboundPendingResult, M as LinkedIdentitiesQuery, N as LinkedIdentitiesResult, Q as SmsVerifyResult, T as ClaimTransferInput, U as ClaimResult, W as ClaimCurrencyInput, X as TransactionStatusResult, Y as GuardianApprovalStatusResult, Z as ServerDestinationsQuery, c as DestinationsResult, _ as PhoneShareContact, $ as PhoneShareInitiateResult, a0 as PhoneShareApproveInput, a1 as PhoneShareApproveResult, a2 as PhoneShareStatusResult } from './types-7Hl0Z1Ta.js';
2
- export { a3 as CurrencyBalance, g as DestinationGame, a4 as InboundPendingItem, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, a5 as LinkedIdentityEmail, m as Rail, V as VerificationMethod } from './types-7Hl0Z1Ta.js';
1
+ import { o as InvoError, H as Http, v as AuthHeader, w as PlatformPurchaseInput, d as CallOptions, x as PlatformPurchaseResult, y as PlatformOrderStatusResult, z as PlatformRefundInput, F as PlatformRefundResult, S as ServerConfig, G as PlayerToken, J as InitiateSendInput, K as InitiateResult, N as InitiateTransferInput, O as CreateCheckoutInput, Q as CreateCheckoutResult, T as PurchaseInput, U as PurchaseResult, W as ConfirmPaymentResult, X as OrderDetailsResult, Y as PurchaseItemInput, Z as PurchaseItemResult, _ as ItemHistoryQuery, $ as ItemHistoryResult, a0 as ItemOrderQuery, a1 as PlayerBalanceQuery, a2 as PlayerBalanceResult, a3 as InboundPendingQuery, a4 as InboundPendingResult, a5 as LinkedIdentitiesQuery, a6 as LinkedIdentitiesResult, a7 as SmsVerifyResult, a8 as ClaimTransferInput, a9 as ClaimResult, aa as ClaimCurrencyInput, ab as TransactionStatusResult, ac as GuardianApprovalStatusResult, ad as ServerDestinationsQuery, f as DestinationsResult, ae as PhoneShareContact, af as PhoneShareInitiateResult, ag as PhoneShareApproveInput, ah as PhoneShareApproveResult, ai as PhoneShareStatusResult } from './types-BHvVjdMV.js';
2
+ export { aj as BillingAddress, ak as CurrencyBalance, k as DestinationGame, al as FundingSource, am as InboundPendingItem, p as InvoErrorInfo, q as InvoHooks, r as InvoRequestInfo, s as InvoResponseInfo, an as LinkedIdentityEmail, ao as PlatformPurchaseStatus, u as Rail, V as VerificationMethod } from './types-BHvVjdMV.js';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -53,6 +53,47 @@ interface ItemPurchasedData {
53
53
  fee_breakdown?: Record<string, unknown>;
54
54
  [key: string]: unknown;
55
55
  }
56
+ /** `platform_commerce.purchased` — a Platform Commerce (ecommerce) purchase completed
57
+ * (balance immediately; card after the payment settles). Fulfill card orders on THIS,
58
+ * never on the browser confirmation. */
59
+ interface PlatformCommercePurchasedData {
60
+ transaction_id: string;
61
+ order_id: string | number;
62
+ /** "balance" | "card". */
63
+ funding_source: string;
64
+ player_email: string;
65
+ identity_id: string;
66
+ item_id: string;
67
+ item_name: string;
68
+ item_quantity: number;
69
+ /** Balance leg only — the network-currency amount. The CARD leg carries `total_price_usd`
70
+ * instead (this field is absent there). */
71
+ total_price?: string;
72
+ /** Balance leg only. */
73
+ unit_price?: string;
74
+ currency_name?: string;
75
+ new_balance?: string;
76
+ /** Card leg only (the USD charged). */
77
+ total_price_usd?: string;
78
+ fee_breakdown?: Record<string, unknown>;
79
+ [key: string]: unknown;
80
+ }
81
+ /** `platform_commerce.refunded` — a Platform Commerce purchase was refunded. INVO keeps
82
+ * its fee (`fee_retained: true`); the customer is made whole minus that fee. */
83
+ interface PlatformCommerceRefundedData {
84
+ order_id: string | number;
85
+ /** "balance" | "card". */
86
+ funding_source: string;
87
+ /** Null when the player row no longer exists at refund time. */
88
+ player_email: string | null;
89
+ /** Nullable for the same reason. */
90
+ identity_id?: string | null;
91
+ refunded_amount: string;
92
+ /** `"usd"` (card) or the literal `"currency"` (balance). */
93
+ amount_unit: string;
94
+ fee_retained: boolean;
95
+ [key: string]: unknown;
96
+ }
56
97
  interface TransferEventData {
57
98
  transaction_id: string;
58
99
  /** "transfer" | "send". */
@@ -79,6 +120,12 @@ type InvoWebhookEvent = (WebhookBase & {
79
120
  }) | (WebhookBase & {
80
121
  event_type: "item.purchased";
81
122
  data: ItemPurchasedData;
123
+ }) | (WebhookBase & {
124
+ event_type: "platform_commerce.purchased";
125
+ data: PlatformCommercePurchasedData;
126
+ }) | (WebhookBase & {
127
+ event_type: "platform_commerce.refunded";
128
+ data: PlatformCommerceRefundedData;
82
129
  }) | (WebhookBase & {
83
130
  event_type: PurchaseEventType;
84
131
  data: PurchaseEventData;
@@ -145,9 +192,71 @@ interface WebhookHandlerOptions {
145
192
  */
146
193
  declare function createWebhookHandler(opts: WebhookHandlerOptions): (request: Request) => Promise<Response>;
147
194
 
195
+ /**
196
+ * @invonetwork/web-sdk/server — NODE entry.
197
+ *
198
+ * InvoServer holds the game secret and runs every server-side call: minting the
199
+ * short-lived player token for the browser, initiating sends/transfers, and the
200
+ * currency-purchase flow (hosted checkout + rail selector). The game secret must
201
+ * NEVER reach the browser.
202
+ *
203
+ * All endpoints here authenticate with the `X-Game-Secret-Key` header.
204
+ */
205
+
206
+ /**
207
+ * Platform Commerce — the ECOMMERCE surface (server side). A PLATFORM tenant (a non-game
208
+ * app: vertical video, creator merch, marketplace) sells items funded by INVO balance OR a
209
+ * real card, with INVO as merchant of record and full refunds. This is NOT item purchase
210
+ * (§4.8) — that is a GAME tenant spending a player's existing game currency on an in-game
211
+ * item (balance only, no card, no refund). Different endpoints, different fee, different
212
+ * settlement. Reached as `invo.platformCommerce.*`.
213
+ */
214
+ declare class PlatformCommerceServer {
215
+ private readonly http;
216
+ private readonly auth;
217
+ constructor(http: Http, auth: AuthHeader);
218
+ /**
219
+ * Create a purchase. The funding source is resolved server-side under lock — the client
220
+ * can request `"balance"` or `"card"`, but the backend verifies the real balance before
221
+ * value moves.
222
+ *
223
+ * - `fundingSource: "balance"` → settles synchronously; result `status:"success"` with
224
+ * `newBalance`/`financialBreakdown`. `totalPrice` is the tenant's network-currency amount.
225
+ * - `fundingSource: "card"` → result `status:"requires_payment"` + `clientSecret`; hand
226
+ * that to the browser `platformCommerce.confirmCardPayment`. `totalPrice` is USD and a
227
+ * `billingAddress` is REQUIRED. The sale is real only on the `platform_commerce.purchased`
228
+ * webhook — never on the client confirmation.
229
+ *
230
+ * Idempotent on `clientRequestId` (a duplicate throws a 409 `err.isDuplicateRequest`).
231
+ * A non-platform tenant throws `err.isNotPlatformTenant` (403).
232
+ *
233
+ * ⚠ Card-leg caveat: if the RESPONSE to a card purchase is lost (timeout after the
234
+ * backend created the order), re-sending the same `clientRequestId` returns the duplicate
235
+ * 409 and the `clientSecret` cannot be re-fetched — reconcile that order via the
236
+ * `platform_commerce.purchased` webhook / `getStatus`, and use a NEW `clientRequestId`
237
+ * for a fresh attempt. The balance leg has no such gap.
238
+ */
239
+ purchase(input: PlatformPurchaseInput, opts?: CallOptions): Promise<PlatformPurchaseResult>;
240
+ /** Poll an order's status: `completed` (balance immediately; card after the webhook),
241
+ * `pending_payment` (card awaiting confirmation), or `refunded`. */
242
+ getStatus(orderId: string | number, opts?: CallOptions): Promise<PlatformOrderStatusResult>;
243
+ /**
244
+ * Refund a completed purchase. Provide EXACTLY ONE of `orderId` or `clientRequestId`.
245
+ * INVO retains its fee — the customer is made whole (balance re-credit or card refund)
246
+ * minus that fee. Idempotent on the order: a second refund throws a 409
247
+ * (`err.isAlreadyRefunded`) — treat that as "already done", not a failure.
248
+ */
249
+ refund(input: PlatformRefundInput, opts?: CallOptions): Promise<PlatformRefundResult>;
250
+ }
148
251
  declare class InvoServer {
149
252
  private readonly http;
150
253
  private readonly auth;
254
+ /**
255
+ * Platform Commerce (ecommerce) — a PLATFORM tenant selling items funded by balance or
256
+ * card, with refunds. DISTINCT from `purchaseItem` (a game tenant spending existing game
257
+ * currency on an in-game item). See {@link PlatformCommerceServer}.
258
+ */
259
+ readonly platformCommerce: PlatformCommerceServer;
151
260
  constructor(config: ServerConfig);
152
261
  /**
153
262
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
@@ -323,4 +432,4 @@ declare class InvoServer {
323
432
  private toInitiateResult;
324
433
  }
325
434
 
326
- export { CallOptions, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, DestinationsResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, ServerDestinationsQuery, SmsVerifyResult, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
435
+ export { CallOptions, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, DestinationsResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, ServerDestinationsQuery, SmsVerifyResult, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };