@solvapay/server 2.4.1 → 2.5.0-preview-4dcf60c628500a6210ba69edbf7ae56ee47fbb3a

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/index.js CHANGED
@@ -4,6 +4,32 @@ import { SolvaPayError as SolvaPayError7 } from "@solvapay/core";
4
4
 
5
5
  // src/client.ts
6
6
  import { SolvaPayError } from "@solvapay/core";
7
+ var API_ERROR_BODY_MAX = 240;
8
+ function apiDebugLog(...args) {
9
+ if (process.env.SOLVAPAY_DEBUG === "true") {
10
+ console.log(...args);
11
+ }
12
+ }
13
+ function isNonJsonResponseBody(body, contentType) {
14
+ const ct = contentType?.split(";")[0]?.trim().toLowerCase() ?? "";
15
+ if (ct.includes("json")) return false;
16
+ const trimmed = body.trimStart();
17
+ if (trimmed.startsWith("<")) return true;
18
+ if (ct && !ct.includes("json")) return true;
19
+ return false;
20
+ }
21
+ async function throwApiError(operation, res) {
22
+ const body = await res.text();
23
+ const contentType = res.headers.get("content-type");
24
+ const nonJson = isNonJsonResponseBody(body, contentType);
25
+ const snippet = body.length > API_ERROR_BODY_MAX ? `${body.slice(0, API_ERROR_BODY_MAX)}\u2026` : body;
26
+ const detail = nonJson ? `non-JSON response (${contentType ?? "unknown content-type"}) \u2014 the API may not have been reached. Body: ${snippet}` : snippet;
27
+ apiDebugLog(`\u274C API Error: ${res.status} - ${detail}`);
28
+ throw new SolvaPayError(`${operation} failed (${res.status}): ${detail}`, {
29
+ status: res.status,
30
+ code: nonJson ? "non_json_response" : void 0
31
+ });
32
+ }
7
33
  function createSolvaPayClient(opts) {
8
34
  const base = opts.apiBaseUrl ?? "https://api.solvapay.com";
9
35
  if (!opts.apiKey) throw new SolvaPayError("Missing apiKey");
@@ -11,12 +37,6 @@ function createSolvaPayClient(opts) {
11
37
  "Content-Type": "application/json",
12
38
  Authorization: `Bearer ${opts.apiKey}`
13
39
  };
14
- const debug = process.env.SOLVAPAY_DEBUG === "true";
15
- const log = (...args) => {
16
- if (debug) {
17
- console.log(...args);
18
- }
19
- };
20
40
  return {
21
41
  // POST: /v1/sdk/limits
22
42
  async checkLimits(params) {
@@ -27,11 +47,7 @@ function createSolvaPayClient(opts) {
27
47
  body: JSON.stringify(params)
28
48
  });
29
49
  if (!res.ok) {
30
- const error = await res.text();
31
- log(`\u274C API Error: ${res.status} - ${error}`);
32
- throw new SolvaPayError(`Check limits failed (${res.status}): ${error}`, {
33
- status: res.status
34
- });
50
+ await throwApiError("Check limits", res);
35
51
  }
36
52
  const result = await res.json();
37
53
  return result;
@@ -45,11 +61,7 @@ function createSolvaPayClient(opts) {
45
61
  body: JSON.stringify(params)
46
62
  });
47
63
  if (!res.ok) {
48
- const error = await res.text();
49
- log(`\u274C API Error: ${res.status} - ${error}`);
50
- throw new SolvaPayError(`Track usage failed (${res.status}): ${error}`, {
51
- status: res.status
52
- });
64
+ await throwApiError("Track usage", res);
53
65
  }
54
66
  return await res.json();
55
67
  },
@@ -62,11 +74,7 @@ function createSolvaPayClient(opts) {
62
74
  body: JSON.stringify(params)
63
75
  });
64
76
  if (!res.ok) {
65
- const error = await res.text();
66
- log(`\u274C API Error: ${res.status} - ${error}`);
67
- throw new SolvaPayError(`Track usage bulk failed (${res.status}): ${error}`, {
68
- status: res.status
69
- });
77
+ await throwApiError("Track usage bulk", res);
70
78
  }
71
79
  return await res.json();
72
80
  },
@@ -79,11 +87,7 @@ function createSolvaPayClient(opts) {
79
87
  body: JSON.stringify(params)
80
88
  });
81
89
  if (!res.ok) {
82
- const error = await res.text();
83
- log(`\u274C API Error: ${res.status} - ${error}`);
84
- throw new SolvaPayError(`Create customer failed (${res.status}): ${error}`, {
85
- status: res.status
86
- });
90
+ await throwApiError("Create customer", res);
87
91
  }
88
92
  const result = await res.json();
89
93
  return {
@@ -99,11 +103,7 @@ function createSolvaPayClient(opts) {
99
103
  body: JSON.stringify(params)
100
104
  });
101
105
  if (!res.ok) {
102
- const error = await res.text();
103
- log(`\u274C API Error: ${res.status} - ${error}`);
104
- throw new SolvaPayError(`Update customer failed (${res.status}): ${error}`, {
105
- status: res.status
106
- });
106
+ await throwApiError("Update customer", res);
107
107
  }
108
108
  const result = await res.json();
109
109
  return {
@@ -131,11 +131,7 @@ function createSolvaPayClient(opts) {
131
131
  headers
132
132
  });
133
133
  if (!res.ok) {
134
- const error = await res.text();
135
- log(`\u274C API Error: ${res.status} - ${error}`);
136
- throw new SolvaPayError(`Get customer failed (${res.status}): ${error}`, {
137
- status: res.status
138
- });
134
+ await throwApiError("Get customer", res);
139
135
  }
140
136
  const result = await res.json();
141
137
  let customer = result;
@@ -169,11 +165,7 @@ function createSolvaPayClient(opts) {
169
165
  body: JSON.stringify(body)
170
166
  });
171
167
  if (!res.ok) {
172
- const error = await res.text();
173
- log(`\u274C API Error: ${res.status} - ${error}`);
174
- throw new SolvaPayError(`Assign credits failed (${res.status}): ${error}`, {
175
- status: res.status
176
- });
168
+ await throwApiError("Assign credits", res);
177
169
  }
178
170
  return await res.json();
179
171
  },
@@ -185,11 +177,7 @@ function createSolvaPayClient(opts) {
185
177
  headers
186
178
  });
187
179
  if (!res.ok) {
188
- const error = await res.text();
189
- log(`\u274C API Error: ${res.status} - ${error}`);
190
- throw new SolvaPayError(`Get merchant failed (${res.status}): ${error}`, {
191
- status: res.status
192
- });
180
+ await throwApiError("Get merchant", res);
193
181
  }
194
182
  return res.json();
195
183
  },
@@ -201,11 +189,7 @@ function createSolvaPayClient(opts) {
201
189
  headers
202
190
  });
203
191
  if (!res.ok) {
204
- const error = await res.text();
205
- log(`\u274C API Error: ${res.status} - ${error}`);
206
- throw new SolvaPayError(`Get platform config failed (${res.status}): ${error}`, {
207
- status: res.status
208
- });
192
+ await throwApiError("Get platform config", res);
209
193
  }
210
194
  return res.json();
211
195
  },
@@ -217,11 +201,7 @@ function createSolvaPayClient(opts) {
217
201
  headers
218
202
  });
219
203
  if (!res.ok) {
220
- const error = await res.text();
221
- log(`\u274C API Error: ${res.status} - ${error}`);
222
- throw new SolvaPayError(`Get product failed (${res.status}): ${error}`, {
223
- status: res.status
224
- });
204
+ await throwApiError("Get product", res);
225
205
  }
226
206
  const result = await res.json();
227
207
  const data = result.data || {};
@@ -236,11 +216,7 @@ function createSolvaPayClient(opts) {
236
216
  headers
237
217
  });
238
218
  if (!res.ok) {
239
- const error = await res.text();
240
- log(`\u274C API Error: ${res.status} - ${error}`);
241
- throw new SolvaPayError(`List products failed (${res.status}): ${error}`, {
242
- status: res.status
243
- });
219
+ await throwApiError("List products", res);
244
220
  }
245
221
  const result = await res.json();
246
222
  const products = Array.isArray(result) ? result : result.products || [];
@@ -258,11 +234,7 @@ function createSolvaPayClient(opts) {
258
234
  body: JSON.stringify(params)
259
235
  });
260
236
  if (!res.ok) {
261
- const error = await res.text();
262
- log(`\u274C API Error: ${res.status} - ${error}`);
263
- throw new SolvaPayError(`Create product failed (${res.status}): ${error}`, {
264
- status: res.status
265
- });
237
+ await throwApiError("Create product", res);
266
238
  }
267
239
  const result = await res.json();
268
240
  return result;
@@ -276,11 +248,7 @@ function createSolvaPayClient(opts) {
276
248
  body: JSON.stringify(params)
277
249
  });
278
250
  if (!res.ok) {
279
- const error = await res.text();
280
- log(`\u274C API Error: ${res.status} - ${error}`);
281
- throw new SolvaPayError(`Bootstrap MCP product failed (${res.status}): ${error}`, {
282
- status: res.status
283
- });
251
+ await throwApiError("Bootstrap MCP product", res);
284
252
  }
285
253
  return await res.json();
286
254
  },
@@ -293,11 +261,7 @@ function createSolvaPayClient(opts) {
293
261
  body: JSON.stringify(params)
294
262
  });
295
263
  if (!res.ok) {
296
- const error = await res.text();
297
- log(`\u274C API Error: ${res.status} - ${error}`);
298
- throw new SolvaPayError(`Configure MCP plans failed (${res.status}): ${error}`, {
299
- status: res.status
300
- });
264
+ await throwApiError("Configure MCP plans", res);
301
265
  }
302
266
  return await res.json();
303
267
  },
@@ -309,11 +273,7 @@ function createSolvaPayClient(opts) {
309
273
  headers
310
274
  });
311
275
  if (!res.ok && res.status !== 404) {
312
- const error = await res.text();
313
- log(`\u274C API Error: ${res.status} - ${error}`);
314
- throw new SolvaPayError(`Delete product failed (${res.status}): ${error}`, {
315
- status: res.status
316
- });
276
+ await throwApiError("Delete product", res);
317
277
  }
318
278
  },
319
279
  // POST: /v1/sdk/products/{productRef}/clone
@@ -325,11 +285,7 @@ function createSolvaPayClient(opts) {
325
285
  body: JSON.stringify(overrides || {})
326
286
  });
327
287
  if (!res.ok) {
328
- const error = await res.text();
329
- log(`\u274C API Error: ${res.status} - ${error}`);
330
- throw new SolvaPayError(`Clone product failed (${res.status}): ${error}`, {
331
- status: res.status
332
- });
288
+ await throwApiError("Clone product", res);
333
289
  }
334
290
  return await res.json();
335
291
  },
@@ -341,11 +297,7 @@ function createSolvaPayClient(opts) {
341
297
  headers
342
298
  });
343
299
  if (!res.ok) {
344
- const error = await res.text();
345
- log(`\u274C API Error: ${res.status} - ${error}`);
346
- throw new SolvaPayError(`List plans failed (${res.status}): ${error}`, {
347
- status: res.status
348
- });
300
+ await throwApiError("List plans", res);
349
301
  }
350
302
  const result = await res.json();
351
303
  const plans = Array.isArray(result) ? result : result.plans || [];
@@ -370,11 +322,7 @@ function createSolvaPayClient(opts) {
370
322
  body: JSON.stringify(params)
371
323
  });
372
324
  if (!res.ok) {
373
- const error = await res.text();
374
- log(`\u274C API Error: ${res.status} - ${error}`);
375
- throw new SolvaPayError(`Create plan failed (${res.status}): ${error}`, {
376
- status: res.status
377
- });
325
+ await throwApiError("Create plan", res);
378
326
  }
379
327
  const result = await res.json();
380
328
  return result;
@@ -388,11 +336,7 @@ function createSolvaPayClient(opts) {
388
336
  body: JSON.stringify(params)
389
337
  });
390
338
  if (!res.ok) {
391
- const error = await res.text();
392
- log(`\u274C API Error: ${res.status} - ${error}`);
393
- throw new SolvaPayError(`Update plan failed (${res.status}): ${error}`, {
394
- status: res.status
395
- });
339
+ await throwApiError("Update plan", res);
396
340
  }
397
341
  return await res.json();
398
342
  },
@@ -404,11 +348,7 @@ function createSolvaPayClient(opts) {
404
348
  headers
405
349
  });
406
350
  if (!res.ok && res.status !== 404) {
407
- const error = await res.text();
408
- log(`\u274C API Error: ${res.status} - ${error}`);
409
- throw new SolvaPayError(`Delete plan failed (${res.status}): ${error}`, {
410
- status: res.status
411
- });
351
+ await throwApiError("Delete plan", res);
412
352
  }
413
353
  },
414
354
  // POST: /payment-intents
@@ -429,11 +369,7 @@ function createSolvaPayClient(opts) {
429
369
  })
430
370
  });
431
371
  if (!res.ok) {
432
- const error = await res.text();
433
- log(`\u274C API Error: ${res.status} - ${error}`);
434
- throw new SolvaPayError(`Create payment intent failed (${res.status}): ${error}`, {
435
- status: res.status
436
- });
372
+ await throwApiError("Create payment intent", res);
437
373
  }
438
374
  return await res.json();
439
375
  },
@@ -457,11 +393,7 @@ function createSolvaPayClient(opts) {
457
393
  })
458
394
  });
459
395
  if (!res.ok) {
460
- const error = await res.text();
461
- log(`\u274C API Error: ${res.status} - ${error}`);
462
- throw new SolvaPayError(`Create topup payment intent failed (${res.status}): ${error}`, {
463
- status: res.status
464
- });
396
+ await throwApiError("Create topup payment intent", res);
465
397
  }
466
398
  return await res.json();
467
399
  },
@@ -481,11 +413,7 @@ function createSolvaPayClient(opts) {
481
413
  })
482
414
  });
483
415
  if (!res.ok) {
484
- const error = await res.text();
485
- log(`\u274C API Error: ${res.status} - ${error}`);
486
- throw new SolvaPayError(`Process payment failed (${res.status}): ${error}`, {
487
- status: res.status
488
- });
416
+ await throwApiError("Process payment", res);
489
417
  }
490
418
  const result = await res.json();
491
419
  return result;
@@ -506,54 +434,20 @@ function createSolvaPayClient(opts) {
506
434
  })
507
435
  });
508
436
  if (!res.ok) {
509
- const error = await res.text();
510
- log(`\u274C API Error: ${res.status} - ${error}`);
511
- throw new SolvaPayError(
512
- `Attach business details failed (${res.status}): ${error}`,
513
- { status: res.status }
514
- );
515
- }
516
- return await res.json();
517
- },
518
- // POST: /v1/sdk/purchases/{purchaseRef}/cancel
519
- async cancelPurchase(params) {
520
- const url = `${base}/v1/sdk/purchases/${params.purchaseRef}/cancel`;
521
- const requestOptions = {
522
- method: "POST",
523
- headers
524
- };
525
- if (params.reason) {
526
- requestOptions.body = JSON.stringify({ reason: params.reason });
527
- }
528
- const res = await fetch(url, requestOptions);
529
- if (!res.ok) {
530
- const error = await res.text();
531
- log(`\u274C API Error: ${res.status} - ${error}`);
532
- if (res.status === 404) {
533
- throw new SolvaPayError(`Purchase not found: ${error}`, { status: 404 });
534
- }
535
- if (res.status === 400) {
536
- throw new SolvaPayError(
537
- `Purchase cannot be cancelled or does not belong to provider: ${error}`,
538
- { status: 400 }
539
- );
540
- }
541
- throw new SolvaPayError(`Cancel purchase failed (${res.status}): ${error}`, {
542
- status: res.status
543
- });
437
+ await throwApiError("Cancel purchase", res);
544
438
  }
545
439
  const responseText = await res.text();
546
440
  let responseData;
547
441
  try {
548
442
  responseData = JSON.parse(responseText);
549
443
  } catch (parseError) {
550
- log(`\u274C Failed to parse response as JSON: ${parseError}`);
444
+ apiDebugLog(`\u274C Failed to parse response as JSON: ${parseError}`);
551
445
  throw new SolvaPayError(
552
446
  `Invalid JSON response from cancel purchase endpoint: ${responseText.substring(0, 200)}`
553
447
  );
554
448
  }
555
449
  if (!responseData || typeof responseData !== "object") {
556
- log(`\u274C Invalid response structure: ${JSON.stringify(responseData)}`);
450
+ apiDebugLog(`\u274C Invalid response structure: ${JSON.stringify(responseData)}`);
557
451
  throw new SolvaPayError(`Invalid response structure from cancel purchase endpoint`);
558
452
  }
559
453
  let result;
@@ -565,7 +459,7 @@ function createSolvaPayClient(opts) {
565
459
  result = responseData.purchase || responseData;
566
460
  }
567
461
  if (!result || typeof result !== "object") {
568
- log(`\u274C Invalid purchase data in response. Full response:`, responseData);
462
+ apiDebugLog(`\u274C Invalid purchase data in response. Full response:`, responseData);
569
463
  throw new SolvaPayError(`Invalid purchase data in cancel purchase response`);
570
464
  }
571
465
  return result;
@@ -578,30 +472,20 @@ function createSolvaPayClient(opts) {
578
472
  headers
579
473
  });
580
474
  if (!res.ok) {
581
- const error = await res.text();
582
- log(`\u274C API Error: ${res.status} - ${error}`);
583
- if (res.status === 404) {
584
- throw new SolvaPayError(`Purchase not found: ${error}`, { status: 404 });
585
- }
586
- if (res.status === 400) {
587
- throw new SolvaPayError(`Purchase cannot be reactivated: ${error}`, { status: 400 });
588
- }
589
- throw new SolvaPayError(`Reactivate purchase failed (${res.status}): ${error}`, {
590
- status: res.status
591
- });
475
+ await throwApiError("Reactivate purchase", res);
592
476
  }
593
477
  const responseText = await res.text();
594
478
  let responseData;
595
479
  try {
596
480
  responseData = JSON.parse(responseText);
597
481
  } catch (parseError) {
598
- log(`\u274C Failed to parse response as JSON: ${parseError}`);
482
+ apiDebugLog(`\u274C Failed to parse response as JSON: ${parseError}`);
599
483
  throw new SolvaPayError(
600
484
  `Invalid JSON response from reactivate purchase endpoint: ${responseText.substring(0, 200)}`
601
485
  );
602
486
  }
603
487
  if (!responseData || typeof responseData !== "object") {
604
- log(`\u274C Invalid response structure: ${JSON.stringify(responseData)}`);
488
+ apiDebugLog(`\u274C Invalid response structure: ${JSON.stringify(responseData)}`);
605
489
  throw new SolvaPayError(`Invalid response structure from reactivate purchase endpoint`);
606
490
  }
607
491
  let result;
@@ -613,7 +497,7 @@ function createSolvaPayClient(opts) {
613
497
  result = responseData.purchase || responseData;
614
498
  }
615
499
  if (!result || typeof result !== "object") {
616
- log(`\u274C Invalid purchase data in response. Full response:`, responseData);
500
+ apiDebugLog(`\u274C Invalid purchase data in response. Full response:`, responseData);
617
501
  throw new SolvaPayError(`Invalid purchase data in reactivate purchase response`);
618
502
  }
619
503
  return result;
@@ -627,11 +511,7 @@ function createSolvaPayClient(opts) {
627
511
  body: JSON.stringify(params)
628
512
  });
629
513
  if (!res.ok) {
630
- const error = await res.text();
631
- log(`\u274C API Error: ${res.status} - ${error}`);
632
- throw new SolvaPayError(`Get user info failed (${res.status}): ${error}`, {
633
- status: res.status
634
- });
514
+ await throwApiError("Get user info", res);
635
515
  }
636
516
  return await res.json();
637
517
  },
@@ -643,11 +523,7 @@ function createSolvaPayClient(opts) {
643
523
  headers
644
524
  });
645
525
  if (!res.ok) {
646
- const error = await res.text();
647
- log(`\u274C API Error: ${res.status} - ${error}`);
648
- throw new SolvaPayError(`Get customer balance failed (${res.status}): ${error}`, {
649
- status: res.status
650
- });
526
+ await throwApiError("Get customer balance", res);
651
527
  }
652
528
  return await res.json();
653
529
  },
@@ -660,11 +536,7 @@ function createSolvaPayClient(opts) {
660
536
  body: JSON.stringify(params)
661
537
  });
662
538
  if (!res.ok) {
663
- const error = await res.text();
664
- log(`\u274C API Error: ${res.status} - ${error}`);
665
- throw new SolvaPayError(`Create checkout session failed (${res.status}): ${error}`, {
666
- status: res.status
667
- });
539
+ await throwApiError("Create checkout session", res);
668
540
  }
669
541
  const result = await res.json();
670
542
  return result;
@@ -678,11 +550,7 @@ function createSolvaPayClient(opts) {
678
550
  body: JSON.stringify(params)
679
551
  });
680
552
  if (!res.ok) {
681
- const error = await res.text();
682
- log(`\u274C API Error: ${res.status} - ${error}`);
683
- throw new SolvaPayError(`Create customer session failed (${res.status}): ${error}`, {
684
- status: res.status
685
- });
553
+ await throwApiError("Create customer session", res);
686
554
  }
687
555
  const result = await res.json();
688
556
  return result;
@@ -696,11 +564,7 @@ function createSolvaPayClient(opts) {
696
564
  body: JSON.stringify(params)
697
565
  });
698
566
  if (!res.ok) {
699
- const error = await res.text();
700
- log(`\u274C API Error: ${res.status} - ${error}`);
701
- throw new SolvaPayError(`Activate plan failed (${res.status}): ${error}`, {
702
- status: res.status
703
- });
567
+ await throwApiError("Activate plan", res);
704
568
  }
705
569
  return await res.json();
706
570
  },
@@ -709,11 +573,7 @@ function createSolvaPayClient(opts) {
709
573
  url.searchParams.set("customerRef", params.customerRef);
710
574
  const res = await fetch(url.toString(), { method: "GET", headers });
711
575
  if (!res.ok) {
712
- const error = await res.text();
713
- log(`\u274C API Error: ${res.status} - ${error}`);
714
- throw new SolvaPayError(`Get payment method failed (${res.status}): ${error}`, {
715
- status: res.status
716
- });
576
+ await throwApiError("Get payment method", res);
717
577
  }
718
578
  return await res.json();
719
579
  },
@@ -722,11 +582,7 @@ function createSolvaPayClient(opts) {
722
582
  url.searchParams.set("customerRef", params.customerRef);
723
583
  const res = await fetch(url.toString(), { method: "GET", headers });
724
584
  if (!res.ok) {
725
- const error = await res.text();
726
- log(`\u274C API Error: ${res.status} - ${error}`);
727
- throw new SolvaPayError(`Get auto-recharge failed (${res.status}): ${error}`, {
728
- status: res.status
729
- });
585
+ await throwApiError("Get auto-recharge", res);
730
586
  }
731
587
  return await res.json();
732
588
  },
@@ -737,11 +593,7 @@ function createSolvaPayClient(opts) {
737
593
  body: JSON.stringify(params)
738
594
  });
739
595
  if (!res.ok) {
740
- const error = await res.text();
741
- log(`\u274C API Error: ${res.status} - ${error}`);
742
- throw new SolvaPayError(`Save auto-recharge failed (${res.status}): ${error}`, {
743
- status: res.status
744
- });
596
+ await throwApiError("Save auto-recharge", res);
745
597
  }
746
598
  return await res.json();
747
599
  },
@@ -750,11 +602,7 @@ function createSolvaPayClient(opts) {
750
602
  url.searchParams.set("customerRef", params.customerRef);
751
603
  const res = await fetch(url.toString(), { method: "DELETE", headers });
752
604
  if (!res.ok) {
753
- const error = await res.text();
754
- log(`\u274C API Error: ${res.status} - ${error}`);
755
- throw new SolvaPayError(`Disable auto-recharge failed (${res.status}): ${error}`, {
756
- status: res.status
757
- });
605
+ await throwApiError("Disable auto-recharge", res);
758
606
  }
759
607
  return await res.json();
760
608
  },
@@ -768,11 +616,7 @@ function createSolvaPayClient(opts) {
768
616
  }
769
617
  const res = await fetch(url.toString(), { method: "GET", headers });
770
618
  if (!res.ok) {
771
- const error = await res.text();
772
- log(`\u274C API Error: ${res.status} - ${error}`);
773
- throw new SolvaPayError(`List purchases failed (${res.status}): ${error}`, {
774
- status: res.status
775
- });
619
+ await throwApiError("List purchases", res);
776
620
  }
777
621
  const data = await res.json();
778
622
  return { purchases: data.purchases ?? [] };
@@ -783,11 +627,7 @@ function createSolvaPayClient(opts) {
783
627
  if (params.limit !== void 0) url.searchParams.set("limit", String(params.limit));
784
628
  const res = await fetch(url.toString(), { method: "GET", headers });
785
629
  if (!res.ok) {
786
- const error = await res.text();
787
- log(`\u274C API Error: ${res.status} - ${error}`);
788
- throw new SolvaPayError(`Get credit activity failed (${res.status}): ${error}`, {
789
- status: res.status
790
- });
630
+ await throwApiError("Get credit activity", res);
791
631
  }
792
632
  return await res.json();
793
633
  }
@@ -795,46 +635,92 @@ function createSolvaPayClient(opts) {
795
635
  }
796
636
 
797
637
  // src/paywall-state.ts
638
+ import { minorUnitsPerMajor } from "@solvapay/core";
798
639
  var CHECKOUT_SESSION_TTL_MINUTES = 15;
799
640
  var DOCS_HINT = "See docs://solvapay/overview.md.";
641
+ function creditSignals(limits) {
642
+ if (!limits) return { isCreditBased: false };
643
+ const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
644
+ const creditsPerCall = limits.balance?.creditsPerUnit ?? limits.creditsPerUnit;
645
+ const isCreditBased = creditBalance !== void 0 || creditsPerCall !== void 0;
646
+ const shortfallCredits = creditBalance !== void 0 && creditsPerCall !== void 0 ? Math.max(0, creditsPerCall - creditBalance) : void 0;
647
+ let remainingCalls;
648
+ if (limits.balance?.remainingUnits !== void 0) {
649
+ remainingCalls = limits.balance.remainingUnits;
650
+ } else if (creditBalance !== void 0 && creditsPerCall !== void 0 && creditsPerCall > 0) {
651
+ remainingCalls = Math.floor(creditBalance / creditsPerCall);
652
+ } else if (limits.remaining >= 0) {
653
+ remainingCalls = limits.remaining;
654
+ }
655
+ return { creditBalance, creditsPerCall, shortfallCredits, remainingCalls, isCreditBased };
656
+ }
657
+ function nextActionFor(state) {
658
+ switch (state.kind) {
659
+ case "activation_required":
660
+ return "activate";
661
+ case "topup_required":
662
+ return "topup";
663
+ case "upgrade_required":
664
+ case "limit_reached":
665
+ return "checkout";
666
+ case "reactivation_required":
667
+ return "account";
668
+ }
669
+ }
670
+ function activePlanRefOf(limits) {
671
+ const ref = limits.planRef ?? limits.plan;
672
+ return ref && ref.length > 0 ? ref : void 0;
673
+ }
800
674
  function classifyPaywallState(limits) {
801
675
  if (!limits) return { kind: "upgrade_required" };
802
- if (limits.activationRequired === true) {
676
+ if (limits.activationRequired === true || limits.paywallReason === "activation_required") {
803
677
  return { kind: "activation_required" };
804
678
  }
679
+ if (limits.paywallReason === "topup_required") {
680
+ return { kind: "topup_required" };
681
+ }
805
682
  if (limits.needsTopUp === true) {
806
683
  return { kind: "topup_required" };
807
684
  }
808
685
  if (limits.needsUpgrade === true) {
809
686
  return { kind: "upgrade_required" };
810
687
  }
811
- const activePlan = limits.plans?.find((p) => p.reference === limits.plan);
812
- const isUsageBased = activePlan?.type === "usage-based" || limits.balance !== void 0;
813
- const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
814
- if (isUsageBased) {
815
- if (creditBalance === 0) return { kind: "topup_required" };
816
- if (creditBalance === void 0 && limits.remaining === 0) {
688
+ const signals = creditSignals(limits);
689
+ if (signals.isCreditBased) {
690
+ if (signals.creditBalance !== void 0 && signals.creditsPerCall !== void 0 && signals.creditBalance < signals.creditsPerCall) {
691
+ return { kind: "topup_required" };
692
+ }
693
+ if (signals.creditBalance === 0) return { kind: "topup_required" };
694
+ if (signals.creditsPerCall === void 0 && limits.remaining === 0) {
817
695
  return { kind: "topup_required" };
818
696
  }
819
697
  }
820
- if (limits.plan.length > 0 && limits.remaining <= 0) {
698
+ const activeRef = activePlanRefOf(limits);
699
+ if ((limits.purchaseRef || activeRef) && limits.remaining <= 0) {
821
700
  return { kind: "limit_reached" };
822
701
  }
702
+ if (signals.isCreditBased) return { kind: "topup_required" };
703
+ if (limits.purchaseRef) return { kind: "limit_reached" };
823
704
  return { kind: "upgrade_required" };
824
705
  }
825
706
  function formatMinor(amountMinor, currency) {
826
- const major = amountMinor / 100;
707
+ const divisor = minorUnitsPerMajor(currency);
708
+ const major = amountMinor / divisor;
709
+ const fractionDigits = divisor === 1 ? 0 : 2;
827
710
  try {
828
711
  return new Intl.NumberFormat("en-US", {
829
712
  style: "currency",
830
713
  currency: currency.toUpperCase(),
831
- minimumFractionDigits: 2,
832
- maximumFractionDigits: 2
714
+ minimumFractionDigits: fractionDigits,
715
+ maximumFractionDigits: fractionDigits
833
716
  }).format(major);
834
717
  } catch {
835
- return `${currency.toUpperCase()} ${major.toFixed(2)}`;
718
+ return `${currency.toUpperCase()} ${divisor === 1 ? String(Math.round(major)) : major.toFixed(2)}`;
836
719
  }
837
720
  }
721
+ function formatCredits(value) {
722
+ return value.toLocaleString("en-US");
723
+ }
838
724
  function meterLabel(gate) {
839
725
  if (!gate.meterName) return "units";
840
726
  return gate.meterName.replace(/_/g, " ");
@@ -842,6 +728,14 @@ function meterLabel(gate) {
842
728
  function namedCheckoutMarkdown(url) {
843
729
  return `[Open checkout](${url})`;
844
730
  }
731
+ function linkLabel(name) {
732
+ return name.replace(/([[\]])/g, "\\$1");
733
+ }
734
+ function planLadder(gate) {
735
+ const linkable = (gate.plans ?? []).filter((p) => typeof p.checkoutUrl === "string" && p.checkoutUrl.length > 0).filter((p) => p.reference !== gate.planRef).sort((a, b) => a.price - b.price).slice(0, 4);
736
+ if (linkable.length === 0) return null;
737
+ return linkable.map((p) => `[${linkLabel(p.name ?? p.reference)}](${p.checkoutUrl})`).join(" \xB7 ");
738
+ }
845
739
  var VIEWER_TOOL = "account";
846
740
  function callViewer(view) {
847
741
  return view ? `call the \`${VIEWER_TOOL}\` tool with view: '${view}'` : `call the \`${VIEWER_TOOL}\` tool`;
@@ -852,25 +746,57 @@ function recoverClause(url, verb, view) {
852
746
  }
853
747
  return ` ${callViewer(view).replace(/^c/, "C")}.`;
854
748
  }
749
+ function hasActivePlan(gate) {
750
+ return Boolean(gate.purchaseRef || gate.planRef && gate.planRef.length > 0);
751
+ }
752
+ function autoRechargeDisabled(gate) {
753
+ return gate.autoRecharge?.enabled === false;
754
+ }
855
755
  function buildGateMessage(state, gate) {
856
756
  const url = gate.checkoutUrl && gate.checkoutUrl.length > 0 ? gate.checkoutUrl : null;
757
+ const ladder = planLadder(gate);
857
758
  switch (state.kind) {
858
759
  case "limit_reached": {
859
760
  const included = gate.included;
860
761
  const price = gate.unitPriceMinor != null && gate.currency ? formatMinor(gate.unitPriceMinor, gate.currency) : null;
861
762
  const usedLine = included ? `You've used ${included.used} of ${included.total} included ${meterLabel(gate)} this period.` : `You've reached the included usage for this period.`;
862
763
  const nextLine = price ? ` The next call is ${price}.` : "";
863
- return `${usedLine}${nextLine}${recoverClause(url, "continue", "checkout")} ${DOCS_HINT}`;
764
+ const planName = gate.planName ?? "This plan";
765
+ const antiTrap = gate.creditBalance !== void 0 && gate.creditBalance > 0 && (gate.creditsPerCall === void 0 || gate.creditsPerCall === 0) ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
766
+ const switchLine = ladder ? ` Or switch plan: ${ladder}.` : recoverClause(url, "continue", "checkout");
767
+ return `${usedLine}${nextLine}${antiTrap}${switchLine} ${DOCS_HINT}`;
864
768
  }
865
769
  case "activation_required":
866
770
  return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`. ${DOCS_HINT}`;
867
771
  case "topup_required": {
868
- const currency = gate.currency ?? gate.balance?.currency ?? "USD";
869
- const presets = [1e3, 2500, 5e3, 1e4].map((m) => formatMinor(m, currency)).join(" \xB7 ");
870
- return `You're out of credits. Top up first (${presets}).${recoverClause(url, "add credits", "topup")} ${DOCS_HINT}`;
871
- }
872
- case "upgrade_required":
772
+ const balance = gate.creditBalance;
773
+ const cost = gate.creditsPerCall;
774
+ const shortfall = gate.shortfallCredits;
775
+ let lead;
776
+ if (balance !== void 0 && cost !== void 0 && shortfall !== void 0) {
777
+ lead = `Out of credits for this call. Balance ${formatCredits(balance)} credits; this call costs ${formatCredits(cost)} credits \u2014 ${formatCredits(shortfall)} short.`;
778
+ } else {
779
+ lead = "Included usage is exhausted.";
780
+ }
781
+ const topup = recoverClause(url, "add credits", "topup");
782
+ const auto = autoRechargeDisabled(gate) ? " Auto-recharge is off \u2014 turn it on from the account tool to avoid this next time." : "";
783
+ const switchLine = ladder ? ` Or switch plan: ${ladder}.` : "";
784
+ return `${lead}${topup}${auto}${switchLine} ${DOCS_HINT}`;
785
+ }
786
+ case "upgrade_required": {
787
+ if (hasActivePlan(gate)) {
788
+ const planName = gate.planName ?? "This plan";
789
+ const lead = `${planName} is active but its included usage is exhausted, and the automatic switch to the next plan did not complete.`;
790
+ if (ladder) {
791
+ return `${lead} Switch here: ${ladder}. ${DOCS_HINT}`;
792
+ }
793
+ return `${lead}${recoverClause(url, "switch plan", "checkout")} ${DOCS_HINT}`;
794
+ }
795
+ if (ladder) {
796
+ return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${DOCS_HINT}`;
797
+ }
873
798
  return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")} ${DOCS_HINT}`;
799
+ }
874
800
  case "reactivation_required":
875
801
  return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan. ${DOCS_HINT}`;
876
802
  }
@@ -878,11 +804,18 @@ function buildGateMessage(state, gate) {
878
804
  function buildNudgeMessage(state, limits) {
879
805
  const url = limits?.checkoutUrl && limits.checkoutUrl.length > 0 ? limits.checkoutUrl : null;
880
806
  const visitClause = url ? `, or ${namedCheckoutMarkdown(url)}` : "";
807
+ const remaining = creditSignals(limits).remainingCalls;
881
808
  switch (state.kind) {
882
809
  case "topup_required":
810
+ if (remaining === 0) {
811
+ return `Heads up \u2014 0 calls left \u2014 the next call needs a top-up. ${callViewer("topup").replace(/^c/, "C")} to add more${visitClause}.`;
812
+ }
883
813
  return `Heads up \u2014 running low on credits. ${callViewer("topup").replace(/^c/, "C")} to add more${visitClause}.`;
884
814
  case "upgrade_required":
885
815
  case "limit_reached":
816
+ if (remaining === 0) {
817
+ return `Heads up \u2014 0 calls left \u2014 the next call needs a top-up. ${callViewer("checkout").replace(/^c/, "C")} for more headroom${visitClause}.`;
818
+ }
886
819
  return `Heads up \u2014 approaching your plan's limit this period. ${callViewer("checkout").replace(/^c/, "C")} for more headroom${visitClause}.`;
887
820
  case "activation_required":
888
821
  return `Heads up \u2014 this plan still needs activation. Call the \`activate_plan\` tool with a \`planRef\`${visitClause}.`;
@@ -898,11 +831,23 @@ function allPaidPlansArePayg(plans) {
898
831
  if (paidPlans.length === 0) return false;
899
832
  return paidPlans.every((p) => p.type === "usage-based" || p.type === "hybrid");
900
833
  }
834
+ function activePlanRefOf2(limits) {
835
+ const ref = limits.planRef ?? limits.plan;
836
+ return ref && ref.length > 0 ? ref : void 0;
837
+ }
901
838
  function activePlanOf(limits) {
902
- if (!limits.plan) return void 0;
903
- return limits.plans?.find((p) => p.reference === limits.plan);
839
+ const ref = activePlanRefOf2(limits);
840
+ if (!ref) return void 0;
841
+ return limits.plans?.find((p) => p.reference === ref);
904
842
  }
905
843
  function includedFromLimits(limits) {
844
+ if (limits.used !== void 0 && limits.limit !== void 0) {
845
+ return {
846
+ total: limits.limit,
847
+ used: limits.used,
848
+ remaining: limits.remaining
849
+ };
850
+ }
906
851
  const total = activePlanOf(limits)?.freeUnits;
907
852
  if (total == null || total === 0) return void 0;
908
853
  const remaining = limits.remaining;
@@ -912,24 +857,49 @@ function includedFromLimits(limits) {
912
857
  remaining
913
858
  };
914
859
  }
915
- function recoveryFields(limits) {
860
+ function recoveryLinks(limits) {
861
+ const links = {};
862
+ if (limits.checkoutUrl) {
863
+ if (limits.checkoutUrl.includes("/topup")) {
864
+ links.topup = limits.checkoutUrl;
865
+ } else {
866
+ links.checkout = limits.checkoutUrl;
867
+ }
868
+ }
869
+ if (limits.confirmationUrl) {
870
+ links.manage = limits.confirmationUrl;
871
+ }
872
+ return Object.keys(links).length > 0 ? links : void 0;
873
+ }
874
+ function recoveryFields(limits, state) {
916
875
  const plan = activePlanOf(limits);
917
876
  const included = includedFromLimits(limits);
918
- const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
877
+ const signals = creditSignals(limits);
878
+ const planRef = activePlanRefOf2(limits);
879
+ const links = recoveryLinks(limits);
919
880
  return {
920
- ...limits.plan ? { planRef: limits.plan } : {},
881
+ ...planRef ? { planRef } : {},
882
+ ...limits.planName !== void 0 ? { planName: limits.planName } : {},
921
883
  ...limits.plans !== void 0 ? { plans: limits.plans } : {},
922
884
  ...limits.meterName !== void 0 ? { meterName: limits.meterName } : {},
923
885
  ...plan?.perUnitChargeMinor != null ? { unitPriceMinor: plan.perUnitChargeMinor, currency: plan.currency } : limits.currency ? { currency: limits.currency } : {},
924
886
  ...included ? { included } : {},
925
- ...creditBalance !== void 0 ? { creditBalance } : {}
887
+ ...signals.creditBalance !== void 0 ? { creditBalance: signals.creditBalance } : {},
888
+ reason: state.kind,
889
+ nextAction: nextActionFor(state),
890
+ ...signals.creditsPerCall !== void 0 ? { creditsPerCall: signals.creditsPerCall } : {},
891
+ ...signals.shortfallCredits !== void 0 ? { shortfallCredits: signals.shortfallCredits } : {},
892
+ ...signals.remainingCalls !== void 0 ? { remainingCalls: signals.remainingCalls } : {},
893
+ ...limits.purchaseRef !== void 0 ? { purchaseRef: limits.purchaseRef } : {},
894
+ ...limits.autoRecharge !== void 0 ? { autoRecharge: limits.autoRecharge } : {},
895
+ ...links ? { links } : {}
926
896
  };
927
897
  }
928
898
  function buildPaywallGate(productRef, limits) {
929
899
  const checkoutUrl = limits.checkoutUrl;
930
- const state = classifyPaywallState({ ...limits, plan: limits.plan ?? "" });
900
+ const state = classifyPaywallState(limits);
931
901
  const useActivationForTopup = !limits.activationRequired && state.kind === "topup_required" && allPaidPlansArePayg(limits.plans);
932
- const recovery = recoveryFields(limits);
902
+ const recovery = recoveryFields(limits, state);
933
903
  const preMessage = limits.activationRequired || useActivationForTopup ? {
934
904
  kind: "activation_required",
935
905
  product: productRef,
@@ -2459,6 +2429,12 @@ async function verifyProductConfiguration(options) {
2459
2429
  };
2460
2430
  } catch (error) {
2461
2431
  const status = error instanceof SolvaPayError4 ? error.status : void 0;
2432
+ const code = error instanceof SolvaPayError4 ? error.code : void 0;
2433
+ if (status === 404 && code === "non_json_response") {
2434
+ throw new Error(
2435
+ `Could not reach ${apiBaseUrl} while verifying SOLVAPAY_PRODUCT_REF "${productRef}": the server returned a non-JSON response (often an offline ngrok tunnel or proxy error page). Check SOLVAPAY_API_BASE_URL and that the API tunnel is running.`
2436
+ );
2437
+ }
2462
2438
  if (status === 404) {
2463
2439
  throw new Error(
2464
2440
  `SOLVAPAY_PRODUCT_REF "${productRef}" does not exist on ${apiBaseUrl}. OAuth dynamic client registration resolves the provider from this ref, so every connection attempt would fail with a 400 "Invalid identifier" and no MCP host could connect. Point SOLVAPAY_PRODUCT_REF at a product that exists on this account (SolvaPay Console \u2192 Products, or \`npx solvapay init\` / \`npx solvapay doctor\`), and check SOLVAPAY_API_BASE_URL is the environment you created the product in.`
@@ -2477,6 +2453,15 @@ async function verifyProductConfiguration(options) {
2477
2453
  }
2478
2454
 
2479
2455
  // src/types/paywall.ts
2456
+ var PAYWALL_REASONS = [
2457
+ "activation_required",
2458
+ "topup_required",
2459
+ "payment_required",
2460
+ "upgrade_required",
2461
+ "limit_reached",
2462
+ "reactivation_required"
2463
+ ];
2464
+ var PAYWALL_NEXT_ACTIONS = ["topup", "checkout", "activate", "account"];
2480
2465
  function isPaywallStructuredContent(value) {
2481
2466
  if (typeof value !== "object" || value === null || !("kind" in value)) {
2482
2467
  return false;
@@ -2494,6 +2479,7 @@ var includedSchema = z.object({
2494
2479
  });
2495
2480
  var recoveryFields2 = {
2496
2481
  planRef: z.string().optional(),
2482
+ planName: z.string().optional(),
2497
2483
  plans: z.array(z.record(z.string(), z.unknown())).optional(),
2498
2484
  meterName: z.string().optional(),
2499
2485
  unitPriceMinor: z.number().optional(),
@@ -2501,7 +2487,23 @@ var recoveryFields2 = {
2501
2487
  included: includedSchema.optional(),
2502
2488
  creditBalance: z.number().optional(),
2503
2489
  balance: z.record(z.string(), z.unknown()).optional(),
2504
- productDetails: z.record(z.string(), z.unknown()).optional()
2490
+ productDetails: z.record(z.string(), z.unknown()).optional(),
2491
+ reason: z.enum(PAYWALL_REASONS).optional(),
2492
+ nextAction: z.enum(PAYWALL_NEXT_ACTIONS).optional(),
2493
+ creditsPerCall: z.number().optional(),
2494
+ shortfallCredits: z.number().optional(),
2495
+ remainingCalls: z.number().optional(),
2496
+ purchaseRef: z.string().optional(),
2497
+ planStatus: z.string().optional(),
2498
+ autoRecharge: z.object({
2499
+ enabled: z.boolean(),
2500
+ status: z.string().optional()
2501
+ }).optional(),
2502
+ links: z.object({
2503
+ topup: z.string().optional(),
2504
+ checkout: z.string().optional(),
2505
+ manage: z.string().optional()
2506
+ }).optional()
2505
2507
  };
2506
2508
  var PaywallStructuredContentSchema = z.discriminatedUnion("kind", [
2507
2509
  z.object({
@@ -3655,6 +3657,7 @@ export {
3655
3657
  createSolvaPayClient,
3656
3658
  createTopupPaymentIntentCore,
3657
3659
  createVirtualTools,
3660
+ creditSignals,
3658
3661
  deriveUsageSnapshot,
3659
3662
  disableAutoRechargeCore,
3660
3663
  getAuthenticatedUserCore,
@@ -3669,8 +3672,11 @@ export {
3669
3672
  isErrorResult,
3670
3673
  isPaywallStructuredContent,
3671
3674
  jsonSchemaToZodRawShape,
3675
+ linkLabel,
3672
3676
  listPlansCore,
3677
+ nextActionFor,
3673
3678
  paywallErrorToClientPayload,
3679
+ planLadder,
3674
3680
  pollBalanceUntilIncreased,
3675
3681
  processPaymentIntentCore,
3676
3682
  processTopupPaymentIntentCore,