@invonetwork/web-sdk 2.4.1 → 2.5.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.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-g1xz5GDk.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-g1xz5GDk.js';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -53,6 +53,44 @@ 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
+ player_email: string;
88
+ refunded_amount: string;
89
+ /** `"usd"` (card) or the literal `"currency"` (balance). */
90
+ amount_unit: string;
91
+ fee_retained: boolean;
92
+ [key: string]: unknown;
93
+ }
56
94
  interface TransferEventData {
57
95
  transaction_id: string;
58
96
  /** "transfer" | "send". */
@@ -79,6 +117,12 @@ type InvoWebhookEvent = (WebhookBase & {
79
117
  }) | (WebhookBase & {
80
118
  event_type: "item.purchased";
81
119
  data: ItemPurchasedData;
120
+ }) | (WebhookBase & {
121
+ event_type: "platform_commerce.purchased";
122
+ data: PlatformCommercePurchasedData;
123
+ }) | (WebhookBase & {
124
+ event_type: "platform_commerce.refunded";
125
+ data: PlatformCommerceRefundedData;
82
126
  }) | (WebhookBase & {
83
127
  event_type: PurchaseEventType;
84
128
  data: PurchaseEventData;
@@ -145,9 +189,65 @@ interface WebhookHandlerOptions {
145
189
  */
146
190
  declare function createWebhookHandler(opts: WebhookHandlerOptions): (request: Request) => Promise<Response>;
147
191
 
192
+ /**
193
+ * @invonetwork/web-sdk/server — NODE entry.
194
+ *
195
+ * InvoServer holds the game secret and runs every server-side call: minting the
196
+ * short-lived player token for the browser, initiating sends/transfers, and the
197
+ * currency-purchase flow (hosted checkout + rail selector). The game secret must
198
+ * NEVER reach the browser.
199
+ *
200
+ * All endpoints here authenticate with the `X-Game-Secret-Key` header.
201
+ */
202
+
203
+ /**
204
+ * Platform Commerce — the ECOMMERCE surface (server side). A PLATFORM tenant (a non-game
205
+ * app: vertical video, creator merch, marketplace) sells items funded by INVO balance OR a
206
+ * real card, with INVO as merchant of record and full refunds. This is NOT item purchase
207
+ * (§4.8) — that is a GAME tenant spending a player's existing game currency on an in-game
208
+ * item (balance only, no card, no refund). Different endpoints, different fee, different
209
+ * settlement. Reached as `invo.platformCommerce.*`.
210
+ */
211
+ declare class PlatformCommerceServer {
212
+ private readonly http;
213
+ private readonly auth;
214
+ constructor(http: Http, auth: AuthHeader);
215
+ /**
216
+ * Create a purchase. The funding source is resolved server-side under lock — the client
217
+ * can request `"balance"` or `"card"`, but the backend verifies the real balance before
218
+ * value moves.
219
+ *
220
+ * - `fundingSource: "balance"` → settles synchronously; result `status:"success"` with
221
+ * `newBalance`/`financialBreakdown`. `totalPrice` is the tenant's network-currency amount.
222
+ * - `fundingSource: "card"` → result `status:"requires_payment"` + `clientSecret`; hand
223
+ * that to the browser `platformCommerce.confirmCardPayment`. `totalPrice` is USD and a
224
+ * `billingAddress` is REQUIRED. The sale is real only on the `platform_commerce.purchased`
225
+ * webhook — never on the client confirmation.
226
+ *
227
+ * Idempotent on `clientRequestId` (a duplicate throws a 409 `err.isDuplicateRequest`).
228
+ * A non-platform tenant throws `err.isNotPlatformTenant` (403).
229
+ */
230
+ purchase(input: PlatformPurchaseInput, opts?: CallOptions): Promise<PlatformPurchaseResult>;
231
+ /** Poll an order's status: `completed` (balance immediately; card after the webhook),
232
+ * `pending_payment` (card awaiting confirmation), or `refunded`. */
233
+ getStatus(orderId: string | number, opts?: CallOptions): Promise<PlatformOrderStatusResult>;
234
+ /**
235
+ * Refund a completed purchase. Provide EXACTLY ONE of `orderId` or `clientRequestId`.
236
+ * INVO retains its fee — the customer is made whole (balance re-credit or card refund)
237
+ * minus that fee. Idempotent on the order: a second refund throws a 409
238
+ * (`err.isAlreadyRefunded`) — treat that as "already done", not a failure.
239
+ */
240
+ refund(input: PlatformRefundInput, opts?: CallOptions): Promise<PlatformRefundResult>;
241
+ }
148
242
  declare class InvoServer {
149
243
  private readonly http;
150
244
  private readonly auth;
245
+ /**
246
+ * Platform Commerce (ecommerce) — a PLATFORM tenant selling items funded by balance or
247
+ * card, with refunds. DISTINCT from `purchaseItem` (a game tenant spending existing game
248
+ * currency on an in-game item). See {@link PlatformCommerceServer}.
249
+ */
250
+ readonly platformCommerce: PlatformCommerceServer;
151
251
  constructor(config: ServerConfig);
152
252
  /**
153
253
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
@@ -323,4 +423,4 @@ declare class InvoServer {
323
423
  private toInitiateResult;
324
424
  }
325
425
 
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 };
426
+ 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.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-SSTZKXPC.js';
2
- export { InvoError } from './chunk-SSTZKXPC.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-ZKYUSYK5.js';
2
+ export { InvoError } from './chunk-ZKYUSYK5.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  var DEFAULT_TOLERANCE_SEC = 300;
@@ -167,7 +167,7 @@ async function hmacHexSubtle(secret, message) {
167
167
  }
168
168
 
169
169
  // src/server.ts
170
- var DEFAULT_UA = "invonetwork-web-sdk/2.4.1 (+https://invo.network)";
170
+ var DEFAULT_UA = "invonetwork-web-sdk/2.5.0 (+https://invo.network)";
171
171
  var MAX_USD_AMOUNT = 999.99;
172
172
  var MAX_ITEM_PRICE = 999999.99;
173
173
  function invalidInput(label, value, why) {
@@ -328,6 +328,194 @@ function requireField(value, field, raw) {
328
328
  }
329
329
  return s;
330
330
  }
331
+ var FUNDING_SOURCES = /* @__PURE__ */ new Set(["balance", "card"]);
332
+ function assertBillingAddress(addr, label) {
333
+ if (!addr || typeof addr !== "object") {
334
+ throw invalidInput(label, addr, 'is required for the "card" funding source');
335
+ }
336
+ const required = [
337
+ [`${label}.line1`, addr.line1],
338
+ [`${label}.city`, addr.city],
339
+ [`${label}.postalCode`, addr.postalCode],
340
+ [`${label}.country`, addr.country]
341
+ ];
342
+ for (const [k, v] of required) {
343
+ if (typeof v !== "string" || !v.trim()) throw invalidInput(k, v, "is required");
344
+ }
345
+ if (!/^[A-Za-z]{2}$/.test(addr.country)) {
346
+ throw invalidInput(`${label}.country`, addr.country, "must be a 2-letter ISO country code");
347
+ }
348
+ }
349
+ function toBillingAddressBody(addr) {
350
+ const body = {
351
+ line1: addr.line1,
352
+ city: addr.city,
353
+ postal_code: addr.postalCode,
354
+ country: addr.country
355
+ };
356
+ if (addr.name) body["name"] = addr.name;
357
+ if (addr.line2) body["line2"] = addr.line2;
358
+ if (addr.state) body["state"] = addr.state;
359
+ return body;
360
+ }
361
+ var PlatformCommerceServer = class {
362
+ constructor(http, auth) {
363
+ this.http = http;
364
+ this.auth = auth;
365
+ }
366
+ /**
367
+ * Create a purchase. The funding source is resolved server-side under lock — the client
368
+ * can request `"balance"` or `"card"`, but the backend verifies the real balance before
369
+ * value moves.
370
+ *
371
+ * - `fundingSource: "balance"` → settles synchronously; result `status:"success"` with
372
+ * `newBalance`/`financialBreakdown`. `totalPrice` is the tenant's network-currency amount.
373
+ * - `fundingSource: "card"` → result `status:"requires_payment"` + `clientSecret`; hand
374
+ * that to the browser `platformCommerce.confirmCardPayment`. `totalPrice` is USD and a
375
+ * `billingAddress` is REQUIRED. The sale is real only on the `platform_commerce.purchased`
376
+ * webhook — never on the client confirmation.
377
+ *
378
+ * Idempotent on `clientRequestId` (a duplicate throws a 409 `err.isDuplicateRequest`).
379
+ * A non-platform tenant throws `err.isNotPlatformTenant` (403).
380
+ */
381
+ async purchase(input, opts) {
382
+ const required = [
383
+ ["clientRequestId", input.clientRequestId],
384
+ ["playerEmail", input.playerEmail],
385
+ ["playerName", input.playerName],
386
+ ["itemId", input.itemId],
387
+ ["itemName", input.itemName]
388
+ ];
389
+ for (const [k, v] of required) {
390
+ if (typeof v !== "string" || !v.trim()) throw invalidInput(k, v, "is required");
391
+ }
392
+ if (!FUNDING_SOURCES.has(input.fundingSource)) {
393
+ throw invalidInput("fundingSource", input.fundingSource, 'must be "balance" or "card"');
394
+ }
395
+ if (!Number.isInteger(input.itemQuantity) || input.itemQuantity < 1 || input.itemQuantity > 1e3) {
396
+ throw invalidInput("itemQuantity", input.itemQuantity, "must be an integer 1..1000");
397
+ }
398
+ const unit = parseMoney(input.unitPrice, MAX_ITEM_PRICE, "unitPrice");
399
+ const total = parseMoney(input.totalPrice, MAX_ITEM_PRICE, "totalPrice");
400
+ const expectedCents = Math.round(unit * input.itemQuantity * 100);
401
+ const totalCents = Math.round(total * 100);
402
+ if (Math.abs(totalCents - expectedCents) > 1) {
403
+ throw invalidInput(
404
+ "totalPrice",
405
+ input.totalPrice,
406
+ `must equal unitPrice \xD7 itemQuantity (\xB10.01): ${unit} \xD7 ${input.itemQuantity}`
407
+ );
408
+ }
409
+ if (input.fundingSource === "card") {
410
+ assertBillingAddress(input.billingAddress, "billingAddress");
411
+ }
412
+ const body = {
413
+ client_request_id: input.clientRequestId,
414
+ funding_source: input.fundingSource,
415
+ player_email: input.playerEmail,
416
+ player_name: input.playerName,
417
+ item_id: input.itemId,
418
+ item_name: input.itemName,
419
+ item_quantity: input.itemQuantity,
420
+ unit_price: input.unitPrice,
421
+ total_price: input.totalPrice
422
+ };
423
+ if (input.playerPhone) body["player_phone"] = input.playerPhone;
424
+ if (input.itemDescription) body["item_description"] = input.itemDescription;
425
+ if (input.itemCategory) body["item_category"] = input.itemCategory;
426
+ if (input.billingAddress) body["billing_address"] = toBillingAddressBody(input.billingAddress);
427
+ const raw = await this.http.post(
428
+ "/api/platform-commerce/purchase",
429
+ body,
430
+ this.auth,
431
+ { idempotent: true, signal: opts?.signal }
432
+ // client_request_id makes this safe to retry (dup → 409)
433
+ );
434
+ const orderIdRaw = raw["order_id"];
435
+ requireField(orderIdRaw, "order_id", raw);
436
+ const status = String(raw["status"] ?? "");
437
+ if (status === "requires_payment" && !raw["client_secret"]) {
438
+ requireField(raw["client_secret"], "client_secret", raw);
439
+ }
440
+ return {
441
+ status,
442
+ fundingSource: String(raw["funding_source"] ?? input.fundingSource),
443
+ orderId: orderIdRaw,
444
+ transactionId: raw["transaction_id"],
445
+ newBalance: raw["new_balance"] ?? null,
446
+ previousBalance: raw["previous_balance"] ?? null,
447
+ currencyName: raw["currency_name"],
448
+ financialBreakdown: raw["financial_breakdown"],
449
+ clientSecret: raw["client_secret"],
450
+ amountUsd: raw["amount_usd"] ?? null,
451
+ raw
452
+ };
453
+ }
454
+ /** Poll an order's status: `completed` (balance immediately; card after the webhook),
455
+ * `pending_payment` (card awaiting confirmation), or `refunded`. */
456
+ async getStatus(orderId, opts) {
457
+ if (orderId == null || String(orderId).trim() === "") {
458
+ throw invalidInput("orderId", orderId, "is required");
459
+ }
460
+ const raw = await this.http.get(
461
+ `/api/platform-commerce/purchase-status/${encodeURIComponent(String(orderId))}`,
462
+ this.auth,
463
+ { signal: opts?.signal }
464
+ );
465
+ return {
466
+ orderId: raw["order_id"] ?? orderId,
467
+ status: String(raw["status"] ?? ""),
468
+ gameCurrencyAmount: raw["game_currency_amount"] ?? null,
469
+ usdAmount: raw["usd_amount"] ?? null,
470
+ paymentMethod: raw["payment_method"],
471
+ createdAt: raw["created_at"],
472
+ raw
473
+ };
474
+ }
475
+ /**
476
+ * Refund a completed purchase. Provide EXACTLY ONE of `orderId` or `clientRequestId`.
477
+ * INVO retains its fee — the customer is made whole (balance re-credit or card refund)
478
+ * minus that fee. Idempotent on the order: a second refund throws a 409
479
+ * (`err.isAlreadyRefunded`) — treat that as "already done", not a failure.
480
+ */
481
+ async refund(input, opts) {
482
+ const hasOrder = input.orderId != null && String(input.orderId).trim() !== "";
483
+ const hasReq = typeof input.clientRequestId === "string" && input.clientRequestId.trim() !== "";
484
+ if (hasOrder === hasReq) {
485
+ throw new InvoError({
486
+ message: "refund requires EXACTLY ONE of orderId or clientRequestId.",
487
+ code: "INVALID_INPUT",
488
+ status: 0
489
+ });
490
+ }
491
+ const body = {};
492
+ if (hasOrder) body["order_id"] = input.orderId;
493
+ else body["client_request_id"] = input.clientRequestId;
494
+ if (input.reason) body["reason"] = input.reason;
495
+ const raw = await this.http.post(
496
+ "/api/platform-commerce/refund",
497
+ body,
498
+ this.auth,
499
+ // Idempotent on the order: a lost-response retry re-refunds nothing (backend 409s
500
+ // "already refunded"), so a transient 5xx/network retry is safe.
501
+ { idempotent: true, signal: opts?.signal }
502
+ );
503
+ const fundingSource = raw["funding_source"];
504
+ return {
505
+ status: String(raw["status"] ?? ""),
506
+ orderId: raw["order_id"] ?? void 0,
507
+ fundingSource,
508
+ transactionId: raw["transaction_id"],
509
+ // Backend key differs per leg: `refunded_amount` (balance) / `refunded_amount_usd` (card).
510
+ refundedAmount: raw["refunded_amount"] ?? raw["refunded_amount_usd"] ?? null,
511
+ // The refund HTTP response carries no unit; derive it (card → USD). The balance leg's
512
+ // unit is the tenant's network currency, not present here — left undefined.
513
+ amountUnit: raw["amount_unit"] ?? (fundingSource === "card" ? "usd" : void 0),
514
+ feeRetained: raw["fee_retained"] === true,
515
+ raw
516
+ };
517
+ }
518
+ };
331
519
  var InvoServer = class {
332
520
  constructor(config) {
333
521
  if (!config.gameSecret) throw new Error("InvoServer requires a `gameSecret`.");
@@ -344,6 +532,7 @@ var InvoServer = class {
344
532
  hooks: config.hooks
345
533
  });
346
534
  this.auth = { kind: "game-secret", secret: config.gameSecret };
535
+ this.platformCommerce = new PlatformCommerceServer(this.http, this.auth);
347
536
  }
348
537
  /**
349
538
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
@@ -1023,6 +1212,6 @@ var InvoServer = class {
1023
1212
  }
1024
1213
  };
1025
1214
 
1026
- export { InvoServer, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
1215
+ export { InvoServer, PlatformCommerceServer, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
1027
1216
  //# sourceMappingURL=server.js.map
1028
1217
  //# sourceMappingURL=server.js.map