@suqo/sdk 1.0.0 → 2.0.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/README.md +2 -1
- package/dist/index.cjs +367 -36
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +544 -93
- package/dist/index.d.ts +544 -93
- package/dist/index.js +367 -37
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -31,12 +31,13 @@ See [`authentication.md`](docs/user/authentication.md) for how the API key deter
|
|
|
31
31
|
| Examples | [`examples/`](examples/) — runnable scripts against your own sandbox |
|
|
32
32
|
| Authentication | [`authentication.md`](docs/user/authentication.md) |
|
|
33
33
|
| Products | [`products.md`](docs/user/products.md) |
|
|
34
|
+
| Checkout sessions | [`checkout-sessions.md`](docs/user/checkout-sessions.md) |
|
|
34
35
|
| Subscriptions | [`subscriptions.md`](docs/user/subscriptions.md) |
|
|
35
36
|
| Customers | [`customers.md`](docs/user/customers.md) |
|
|
36
37
|
| Webhooks | [`webhooks.md`](docs/user/webhooks.md) |
|
|
37
38
|
| Pagination | [`pagination.md`](docs/user/pagination.md) |
|
|
38
39
|
| Errors | [`errors.md`](docs/user/errors.md) |
|
|
39
|
-
| Rate limiting
|
|
40
|
+
| Rate limiting | [`rate-limiting.md`](docs/user/rate-limiting.md) |
|
|
40
41
|
| Idempotency _(planned)_ | [`idempotency.md`](docs/user/idempotency.md) |
|
|
41
42
|
|
|
42
43
|
Every exported class and method also carries inline TSDoc — your editor will show it on hover without needing to open these files.
|
package/dist/index.cjs
CHANGED
|
@@ -26,6 +26,8 @@ var KycRequiredError = class extends SuqoError {
|
|
|
26
26
|
if (options.kycStatus !== void 0) this.kycStatus = options.kycStatus;
|
|
27
27
|
}
|
|
28
28
|
};
|
|
29
|
+
var PermissionDeniedError = class extends SuqoError {
|
|
30
|
+
};
|
|
29
31
|
var ValidationError = class extends SuqoError {
|
|
30
32
|
constructor(message, options = {}) {
|
|
31
33
|
super(message, options);
|
|
@@ -50,7 +52,20 @@ function isRecord(value) {
|
|
|
50
52
|
return typeof value === "object" && value !== null;
|
|
51
53
|
}
|
|
52
54
|
|
|
55
|
+
// src/utils/assertPathId.ts
|
|
56
|
+
function assertPathId(id, method, reserved = []) {
|
|
57
|
+
if (!id || id === "." || id === "..") {
|
|
58
|
+
throw new SuqoConfigError(`${method}() requires a non-empty id other than "." or ".."`);
|
|
59
|
+
}
|
|
60
|
+
if (reserved.includes(id)) {
|
|
61
|
+
throw new SuqoConfigError(`${method}() was given "${id}", which is a route name, not an id`);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
|
|
53
65
|
// src/errors/mapHttpError.ts
|
|
66
|
+
function isMessageList(body) {
|
|
67
|
+
return Array.isArray(body) && body.length > 0 && body.every((item) => typeof item === "string");
|
|
68
|
+
}
|
|
54
69
|
function isDetailShaped(body) {
|
|
55
70
|
return isRecord(body) && typeof body.detail === "string" && body.detail.length > 0;
|
|
56
71
|
}
|
|
@@ -85,14 +100,19 @@ function mapHttpError(input) {
|
|
|
85
100
|
case 401:
|
|
86
101
|
return new AuthenticationError(messageFrom(body, fallbackMessage), base);
|
|
87
102
|
case 403: {
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
103
|
+
if (isRecord(body) && typeof body.status_code === "string") {
|
|
104
|
+
const message = messageFrom(body, "KYC verification needed to perform this action.");
|
|
105
|
+
return new KycRequiredError(message, { ...base, kycStatus: body.status_code });
|
|
106
|
+
}
|
|
107
|
+
return new PermissionDeniedError(messageFrom(body, "You do not have permission to perform this action."), base);
|
|
91
108
|
}
|
|
92
109
|
case 400: {
|
|
93
110
|
if (isDetailShaped(body)) {
|
|
94
111
|
return new ValidationError(body.detail, base);
|
|
95
112
|
}
|
|
113
|
+
if (isMessageList(body)) {
|
|
114
|
+
return new ValidationError(body.join(" "), { ...base, fieldErrors: {} });
|
|
115
|
+
}
|
|
96
116
|
return new ValidationError("Validation failed.", { ...base, fieldErrors: fieldErrorsFrom(body) });
|
|
97
117
|
}
|
|
98
118
|
case 404:
|
|
@@ -212,6 +232,12 @@ function parseRetryAfterMs(headerValue, now = Date.now()) {
|
|
|
212
232
|
const delta = Math.max(dateMs - now, 0);
|
|
213
233
|
return Math.min(delta, MAX_RETRY_AFTER_MS);
|
|
214
234
|
}
|
|
235
|
+
function parseRetryAfterDetailMs(body) {
|
|
236
|
+
if (!isRecord(body) || typeof body.detail !== "string") return void 0;
|
|
237
|
+
const match = /available in (\d+(?:\.\d+)?) seconds?/i.exec(body.detail);
|
|
238
|
+
if (!match) return void 0;
|
|
239
|
+
return Math.min(Number(match[1]) * 1e3, MAX_RETRY_AFTER_MS);
|
|
240
|
+
}
|
|
215
241
|
|
|
216
242
|
// src/http/signals.ts
|
|
217
243
|
function combineSignals(signals) {
|
|
@@ -276,8 +302,8 @@ var HttpClient = class {
|
|
|
276
302
|
* send, not just `unknown`.
|
|
277
303
|
*/
|
|
278
304
|
async request(options) {
|
|
279
|
-
if (options.method === "GET" && options.body !== void 0) {
|
|
280
|
-
throw new TypeError(
|
|
305
|
+
if ((options.method === "GET" || options.method === "DELETE") && options.body !== void 0) {
|
|
306
|
+
throw new TypeError(`HttpClient.request: a ${options.method} request cannot carry a body.`);
|
|
281
307
|
}
|
|
282
308
|
let url;
|
|
283
309
|
try {
|
|
@@ -302,7 +328,7 @@ var HttpClient = class {
|
|
|
302
328
|
return await parseJsonBody(response);
|
|
303
329
|
}
|
|
304
330
|
const body = await parseJsonBody(response);
|
|
305
|
-
const retryAfter = parseRetryAfterMs(response.headers.get("Retry-After"));
|
|
331
|
+
const retryAfter = parseRetryAfterMs(response.headers.get("Retry-After")) ?? (response.status === 429 ? parseRetryAfterDetailMs(body) : void 0);
|
|
306
332
|
if (!isLastAttempt && retryable && isRetryableFailure({ networkError: false, status: response.status })) {
|
|
307
333
|
await this.#sleepOrAbort(retryAfter ?? backoffDelayMs(attempt - 1), options.signal, timeoutMs);
|
|
308
334
|
continue;
|
|
@@ -360,7 +386,7 @@ var HttpClient = class {
|
|
|
360
386
|
if (isWrite) {
|
|
361
387
|
headers["Content-Type"] = "application/json";
|
|
362
388
|
}
|
|
363
|
-
const body =
|
|
389
|
+
const body = "body" in options ? options.body : void 0;
|
|
364
390
|
const { signal, cleanup } = combineSignals([AbortSignal.timeout(timeoutMs), options.signal]);
|
|
365
391
|
try {
|
|
366
392
|
const init = {
|
|
@@ -430,14 +456,23 @@ function deserializeBillingPeriod(wire) {
|
|
|
430
456
|
isCurrent: wire.is_current,
|
|
431
457
|
isLimited: wire.is_limited,
|
|
432
458
|
isArchived: wire.is_archived,
|
|
433
|
-
offers: wire.offers
|
|
459
|
+
offers: (wire.offers ?? []).map(deserializeOffer)
|
|
460
|
+
};
|
|
461
|
+
}
|
|
462
|
+
function deserializeOffer(wire) {
|
|
463
|
+
return {
|
|
464
|
+
id: wire.id,
|
|
465
|
+
discountAmount: wire.discount_amount,
|
|
466
|
+
startsAt: wire.starts_at ?? null,
|
|
467
|
+
validUntil: wire.valid_until ?? null,
|
|
468
|
+
isActive: wire.is_active
|
|
434
469
|
};
|
|
435
470
|
}
|
|
436
471
|
function deserializePlan(wire) {
|
|
437
472
|
return {
|
|
438
473
|
planId: wire.plan_id,
|
|
439
474
|
planName: wire.plan_name,
|
|
440
|
-
description: wire.description,
|
|
475
|
+
description: wire.description ?? null,
|
|
441
476
|
// `openapi.yaml`'s Product schema has no `required` list at all, so `billing_periods` being
|
|
442
477
|
// omitted entirely (not just an empty array) is spec-legal — `?? []` degrades to an empty
|
|
443
478
|
// list instead of `.map` throwing on `undefined` (found in review, reproduced).
|
|
@@ -447,25 +482,25 @@ function deserializePlan(wire) {
|
|
|
447
482
|
function deserializeProductVat(wire) {
|
|
448
483
|
return {
|
|
449
484
|
isVatActive: wire.is_vat_active,
|
|
450
|
-
vatType: wire.vat_type,
|
|
451
|
-
vatPercentage: wire.vat_percentage
|
|
485
|
+
vatType: wire.vat_type ?? null,
|
|
486
|
+
vatPercentage: wire.vat_percentage ?? null
|
|
452
487
|
};
|
|
453
488
|
}
|
|
454
489
|
function deserializeProduct(wire) {
|
|
455
490
|
return {
|
|
456
491
|
productId: wire.product_id,
|
|
457
492
|
name: wire.name,
|
|
458
|
-
description: wire.description,
|
|
493
|
+
description: wire.description ?? null,
|
|
459
494
|
type: wire.type,
|
|
460
495
|
isActive: wire.is_active,
|
|
461
|
-
termsAndConditions: wire.terms_and_conditions,
|
|
462
|
-
featuresAndBenefits: wire.features_and_benefits,
|
|
496
|
+
termsAndConditions: wire.terms_and_conditions ?? null,
|
|
497
|
+
featuresAndBenefits: wire.features_and_benefits ?? null,
|
|
463
498
|
// `== null` (not `=== null`) is deliberate — it catches both an explicit `null` and an
|
|
464
499
|
// entirely omitted `vat` key. `openapi.yaml` has no `required` list for Product, so omitting
|
|
465
500
|
// `vat` is spec-legal, and the old `=== null` check crashed on `deserializeProductVat(undefined)`
|
|
466
501
|
// when that happened (found in review, reproduced).
|
|
467
502
|
vat: wire.vat == null ? null : deserializeProductVat(wire.vat),
|
|
468
|
-
productImage: wire.product_image,
|
|
503
|
+
productImage: (wire.product_image ?? []).map((img) => ({ image: img.image, imageOrder: img.image_order })),
|
|
469
504
|
// Same reasoning as `billingPeriods` above — `plan` being omitted entirely is spec-legal.
|
|
470
505
|
plan: (wire.plan ?? []).map(deserializePlan),
|
|
471
506
|
totalSubscribers: wire.total_subscribers,
|
|
@@ -573,18 +608,26 @@ function deserializeSubscriptionCustomer(wire) {
|
|
|
573
608
|
}
|
|
574
609
|
return customer;
|
|
575
610
|
}
|
|
611
|
+
function deserializeCheckoutSessionResponse(wire) {
|
|
612
|
+
return {
|
|
613
|
+
publicId: wire.public_id,
|
|
614
|
+
expiresAt: wire.expires_at,
|
|
615
|
+
checkoutUrl: wire.checkout_url
|
|
616
|
+
};
|
|
617
|
+
}
|
|
576
618
|
|
|
577
619
|
// src/resources/subscriptions.ts
|
|
578
620
|
var SUBSCRIPTIONS_PATH = "/api/v1/subscriptions";
|
|
621
|
+
var RENEW_PATH = "/api/v1/subscription/renew";
|
|
579
622
|
function deserializeSubscriptionProduct(wire) {
|
|
580
623
|
return {
|
|
581
|
-
productId: wire.product_id,
|
|
582
|
-
name: wire.name,
|
|
583
|
-
planName: wire.plan_name,
|
|
584
|
-
pbpId: wire.pbp_id,
|
|
585
|
-
label: wire.label,
|
|
586
|
-
price: wire.price,
|
|
587
|
-
currency: wire.currency
|
|
624
|
+
productId: wire.product_id ?? null,
|
|
625
|
+
name: wire.name ?? null,
|
|
626
|
+
planName: wire.plan_name ?? null,
|
|
627
|
+
pbpId: wire.pbp_id ?? null,
|
|
628
|
+
label: wire.label ?? null,
|
|
629
|
+
price: wire.price ?? null,
|
|
630
|
+
currency: wire.currency ?? null
|
|
588
631
|
};
|
|
589
632
|
}
|
|
590
633
|
function deserializeSubscription(wire) {
|
|
@@ -656,13 +699,28 @@ var SubscriptionsResource = class {
|
|
|
656
699
|
});
|
|
657
700
|
}
|
|
658
701
|
/**
|
|
702
|
+
* Retrieves one of your own subscriptions by id. Built from Swagger's schema; not yet checked
|
|
703
|
+
* against a captured response.
|
|
704
|
+
*/
|
|
705
|
+
async retrieve(id) {
|
|
706
|
+
assertPathId(id, "subscriptions.retrieve");
|
|
707
|
+
const wire = await this.#http.request({
|
|
708
|
+
method: "GET",
|
|
709
|
+
path: `${SUBSCRIPTIONS_PATH}/${encodeURIComponent(id)}`
|
|
710
|
+
});
|
|
711
|
+
return deserializeSubscription(wire);
|
|
712
|
+
}
|
|
713
|
+
/**
|
|
714
|
+
* **Legacy** — prefer `checkoutSessions.create()`, which takes up to ten items in one payment
|
|
715
|
+
* and doesn't need a full customer object. Still supported; existing integrations keep working.
|
|
716
|
+
*
|
|
659
717
|
* Creates a subscription in `pending_checkout` state and returns a checkout URL for the buyer
|
|
660
718
|
* to pay (SDK-SPEC.md §5). Redirect the buyer to `checkoutUrl`; the return is **not** proof of
|
|
661
719
|
* payment — learn the real outcome via the `checkout.succeeded`/`checkout.failed` webhooks.
|
|
662
720
|
*
|
|
663
|
-
*
|
|
664
|
-
*
|
|
665
|
-
*
|
|
721
|
+
* `customer.email` identifies the buyer. A buyer may hold only one live recurring subscription
|
|
722
|
+
* per product: a second one on any billing period of the same product throws `ValidationError`.
|
|
723
|
+
* To restart an inactive subscription, use `renew()` rather than creating a new one.
|
|
666
724
|
*
|
|
667
725
|
* Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
|
|
668
726
|
*/
|
|
@@ -682,11 +740,14 @@ var SubscriptionsResource = class {
|
|
|
682
740
|
/**
|
|
683
741
|
* Schedules cancellation for the end of the current billing period — **not** immediate
|
|
684
742
|
* (confirmed with backend 2026-08-17; immediate cancellation is a future capability). Status
|
|
685
|
-
* moves to `pending_cancellation`; the subscription stays active until the period ends.
|
|
743
|
+
* moves to `pending_cancellation`; the subscription stays active until the period ends. Calling
|
|
744
|
+
* it on a subscription already cancelled or pending cancellation returns it unchanged, so a
|
|
745
|
+
* retry by the caller is safe.
|
|
686
746
|
*
|
|
687
747
|
* Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
|
|
688
748
|
*/
|
|
689
749
|
async cancel(id) {
|
|
750
|
+
assertPathId(id, "subscriptions.cancel");
|
|
690
751
|
return this.#http.request({
|
|
691
752
|
method: "POST",
|
|
692
753
|
path: `${SUBSCRIPTIONS_PATH}/${encodeURIComponent(id)}/cancel`
|
|
@@ -709,18 +770,37 @@ var SubscriptionsResource = class {
|
|
|
709
770
|
});
|
|
710
771
|
}
|
|
711
772
|
/**
|
|
712
|
-
*
|
|
713
|
-
*
|
|
714
|
-
*
|
|
773
|
+
* Undoes a scheduled cancellation and returns the subscription to `active`. An already-active
|
|
774
|
+
* subscription is returned unchanged. Once a subscription is `cancelled` there is nothing to
|
|
775
|
+
* resume — use `renew()`.
|
|
715
776
|
*
|
|
716
777
|
* Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
|
|
717
778
|
*/
|
|
718
779
|
async resume(id) {
|
|
780
|
+
assertPathId(id, "subscriptions.resume");
|
|
719
781
|
return this.#http.request({
|
|
720
782
|
method: "POST",
|
|
721
783
|
path: `${SUBSCRIPTIONS_PATH}/${encodeURIComponent(id)}/resume`
|
|
722
784
|
});
|
|
723
785
|
}
|
|
786
|
+
/**
|
|
787
|
+
* Opens a checkout session for the next payment on one of your own subscriptions, reusing its
|
|
788
|
+
* customer and billing period (or partner-priced item) rather than resubmitting them — how an
|
|
789
|
+
* inactive subscription is restarted. Send the buyer to the returned `checkoutUrl`, and learn
|
|
790
|
+
* the outcome from the `checkout.*` webhooks, matched on `publicId`.
|
|
791
|
+
*
|
|
792
|
+
* A cancelled or archived subscription, or a paid one-time purchase, can't be renewed: that
|
|
793
|
+
* throws `ValidationError`. Not auto-retryable — writes never retry until idempotency ships
|
|
794
|
+
* (SDK-SPEC.md §8, §12).
|
|
795
|
+
*/
|
|
796
|
+
async renew(subscriptionId) {
|
|
797
|
+
const wire = await this.#http.request({
|
|
798
|
+
method: "POST",
|
|
799
|
+
path: RENEW_PATH,
|
|
800
|
+
body: { subscription_id: subscriptionId }
|
|
801
|
+
});
|
|
802
|
+
return deserializeCheckoutSessionResponse(wire);
|
|
803
|
+
}
|
|
724
804
|
};
|
|
725
805
|
|
|
726
806
|
// src/resources/customers.ts
|
|
@@ -728,12 +808,22 @@ var CUSTOMERS_PATH = "/api/v1/customers";
|
|
|
728
808
|
function deserializeCustomer(wire) {
|
|
729
809
|
return {
|
|
730
810
|
id: wire.id,
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
811
|
+
// `?? null` on all four nullable fields (not a direct pass-through, found in review): catches
|
|
812
|
+
// both an explicit `null` and an entirely omitted key — see the WireCustomer comment above.
|
|
813
|
+
buyerPhone: wire.buyer_phone ?? null,
|
|
814
|
+
buyerEmail: wire.buyer_email ?? null,
|
|
815
|
+
fullName: wire.full_name ?? null,
|
|
816
|
+
address: wire.address ?? null,
|
|
734
817
|
createdAt: wire.created_at
|
|
735
818
|
};
|
|
736
819
|
}
|
|
820
|
+
function serializeCustomerFields(params) {
|
|
821
|
+
const wire = {};
|
|
822
|
+
if (params.fullName !== void 0) wire.full_name = params.fullName;
|
|
823
|
+
if (params.email !== void 0) wire.email = params.email;
|
|
824
|
+
if (params.address !== void 0) wire.address = params.address;
|
|
825
|
+
return wire;
|
|
826
|
+
}
|
|
737
827
|
var CustomersResource = class {
|
|
738
828
|
#http;
|
|
739
829
|
constructor(http) {
|
|
@@ -760,21 +850,260 @@ var CustomersResource = class {
|
|
|
760
850
|
});
|
|
761
851
|
}
|
|
762
852
|
/**
|
|
763
|
-
* Retrieves a single customer by id
|
|
764
|
-
*
|
|
853
|
+
* Retrieves a single customer by id — an opaque prefixed string (e.g. `"cus_1ce18d624"`), like
|
|
854
|
+
* `pbp_...` on billing periods, not an integer and not a UUID (Bug #42 corrected the previously
|
|
855
|
+
* wrong `number` type/doc claim here).
|
|
765
856
|
*/
|
|
766
857
|
async retrieve(id) {
|
|
858
|
+
assertPathId(id, "customers.retrieve");
|
|
767
859
|
const wire = await this.#http.request({
|
|
768
860
|
method: "GET",
|
|
769
861
|
path: `${CUSTOMERS_PATH}/${encodeURIComponent(id)}`
|
|
770
862
|
});
|
|
771
863
|
return deserializeCustomer(wire);
|
|
772
864
|
}
|
|
865
|
+
/**
|
|
866
|
+
* Records a customer on the seller's account without opening a subscription. `email` identifies
|
|
867
|
+
* the buyer and is required; `phone` is optional. The name and address are the seller's own copy
|
|
868
|
+
* and aren't shared with other sellers. Pass the returned `id` to `checkoutSessions.create()` as
|
|
869
|
+
* `customerId` to send the buyer straight to payment.
|
|
870
|
+
*
|
|
871
|
+
* An email or phone the seller already holds updates that existing customer instead of creating
|
|
872
|
+
* a second one (the API answers `200` rather than `201`; both resolve to the `Customer` here).
|
|
873
|
+
* That makes this call safe for the caller to retry — but, like every write, the SDK never
|
|
874
|
+
* retries it automatically (SDK-SPEC.md §8, §12).
|
|
875
|
+
*/
|
|
876
|
+
async create(params) {
|
|
877
|
+
const wire = await this.#http.request({
|
|
878
|
+
method: "POST",
|
|
879
|
+
path: CUSTOMERS_PATH,
|
|
880
|
+
body: {
|
|
881
|
+
...serializeCustomerFields(params),
|
|
882
|
+
...params.phone !== void 0 ? { phone: params.phone } : {}
|
|
883
|
+
}
|
|
884
|
+
});
|
|
885
|
+
return deserializeCustomer(wire);
|
|
886
|
+
}
|
|
887
|
+
/**
|
|
888
|
+
* Updates the seller's copy of a customer's name, email or address. Send only the fields you're
|
|
889
|
+
* changing; `""` clears a field. The phone can't be changed.
|
|
890
|
+
*
|
|
891
|
+
* Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
|
|
892
|
+
*/
|
|
893
|
+
async update(id, params) {
|
|
894
|
+
assertPathId(id, "customers.update");
|
|
895
|
+
const wire = await this.#http.request({
|
|
896
|
+
method: "PATCH",
|
|
897
|
+
path: `${CUSTOMERS_PATH}/${encodeURIComponent(id)}`,
|
|
898
|
+
body: serializeCustomerFields(params)
|
|
899
|
+
});
|
|
900
|
+
return deserializeCustomer(wire);
|
|
901
|
+
}
|
|
902
|
+
};
|
|
903
|
+
|
|
904
|
+
// src/resources/checkoutSessions.ts
|
|
905
|
+
var CHECKOUT_SESSIONS_PATH = "/api/v1/checkout-sessions";
|
|
906
|
+
function deserializeLineItem(wire) {
|
|
907
|
+
return {
|
|
908
|
+
name: wire.name,
|
|
909
|
+
amount: wire.amount,
|
|
910
|
+
pbpId: wire.pbp_id ?? null,
|
|
911
|
+
currency: wire.currency,
|
|
912
|
+
vatType: wire.vat_type ?? null,
|
|
913
|
+
vatPercentage: wire.vat_percentage ?? null,
|
|
914
|
+
discountAmount: wire.discount_amount ?? null,
|
|
915
|
+
intervalType: wire.interval_type,
|
|
916
|
+
intervalCount: wire.interval_count,
|
|
917
|
+
displayLabel: wire.display_label,
|
|
918
|
+
currentPeriodEnd: wire.current_period_end ?? null,
|
|
919
|
+
extendsTo: wire.extends_to ?? null,
|
|
920
|
+
nextPaymentDue: wire.next_payment_due ?? null,
|
|
921
|
+
// Each kind carries one of these and not the other, so they stay absent rather than null.
|
|
922
|
+
...wire.image_urls !== void 0 ? { imageUrls: wire.image_urls } : {},
|
|
923
|
+
...wire.plan_name !== void 0 ? { planName: wire.plan_name } : {}
|
|
924
|
+
};
|
|
925
|
+
}
|
|
926
|
+
function deserializeCheckoutSession(wire) {
|
|
927
|
+
return {
|
|
928
|
+
publicId: wire.public_id,
|
|
929
|
+
lineItems: (wire.line_items ?? []).map(deserializeLineItem),
|
|
930
|
+
customerId: wire.customer_id ?? null,
|
|
931
|
+
sellerDetails: {
|
|
932
|
+
id: wire.seller_details.id,
|
|
933
|
+
phone: wire.seller_details.phone,
|
|
934
|
+
businessLogo: wire.seller_details.business_logo ?? null,
|
|
935
|
+
businessName: wire.seller_details.business_name
|
|
936
|
+
},
|
|
937
|
+
returnUrl: wire.return_url,
|
|
938
|
+
expiresAt: wire.expires_at,
|
|
939
|
+
completedAt: wire.completed_at ?? null,
|
|
940
|
+
isExpired: wire.is_expired,
|
|
941
|
+
sessionType: wire.session_type ?? null
|
|
942
|
+
};
|
|
943
|
+
}
|
|
944
|
+
function serializeItem(item) {
|
|
945
|
+
if (item.pbpId !== void 0) return { pbp_id: item.pbpId };
|
|
946
|
+
return {
|
|
947
|
+
name: item.name,
|
|
948
|
+
amount: item.amount,
|
|
949
|
+
interval_type: item.intervalType,
|
|
950
|
+
interval_count: item.intervalCount
|
|
951
|
+
};
|
|
952
|
+
}
|
|
953
|
+
var CheckoutSessionsResource = class {
|
|
954
|
+
#http;
|
|
955
|
+
constructor(http) {
|
|
956
|
+
this.#http = http;
|
|
957
|
+
}
|
|
958
|
+
/**
|
|
959
|
+
* Opens a checkout session for one to ten items and returns a URL for the buyer to pay. Prices
|
|
960
|
+
* are snapshotted now, so a plan edited later can't change what the buyer was shown. Redirect
|
|
961
|
+
* the buyer to `checkoutUrl`; the return to `returnUrl` is **not** proof of payment — learn the
|
|
962
|
+
* outcome from `checkout.succeeded`/`checkout.failed`, matched on `publicId` (`session_id`).
|
|
963
|
+
*
|
|
964
|
+
* The API's one rate-limited endpoint: 20 sessions a minute per account. Past that it throws
|
|
965
|
+
* `RateLimitError` with `retryAfter` set. Never retried automatically — writes don't retry until
|
|
966
|
+
* idempotency ships (SDK-SPEC.md §8, §12) — so open a session when the buyer commits to paying,
|
|
967
|
+
* not on page load.
|
|
968
|
+
*/
|
|
969
|
+
async create(params) {
|
|
970
|
+
const wire = await this.#http.request({
|
|
971
|
+
method: "POST",
|
|
972
|
+
path: CHECKOUT_SESSIONS_PATH,
|
|
973
|
+
body: {
|
|
974
|
+
items: params.items.map(serializeItem),
|
|
975
|
+
return_url: params.returnUrl,
|
|
976
|
+
...params.customerId !== void 0 ? { customer_id: params.customerId } : {}
|
|
977
|
+
}
|
|
978
|
+
});
|
|
979
|
+
return deserializeCheckoutSessionResponse(wire);
|
|
980
|
+
}
|
|
981
|
+
/**
|
|
982
|
+
* Reads one of your own open sessions: its line items, customer, seller and expiry. Once paid,
|
|
983
|
+
* expired, unknown or someone else's, it throws `NotFoundError`.
|
|
984
|
+
*/
|
|
985
|
+
async retrieve(id) {
|
|
986
|
+
assertPathId(id, "checkoutSessions.retrieve");
|
|
987
|
+
const wire = await this.#http.request({
|
|
988
|
+
method: "GET",
|
|
989
|
+
path: `${CHECKOUT_SESSIONS_PATH}/${encodeURIComponent(id)}`
|
|
990
|
+
});
|
|
991
|
+
return deserializeCheckoutSession(wire);
|
|
992
|
+
}
|
|
773
993
|
};
|
|
994
|
+
var WEBHOOKS_PATH = "/api/v1/webhooks";
|
|
995
|
+
var RESERVED_SEGMENTS = ["secret"];
|
|
996
|
+
function deserializeWebhook(wire) {
|
|
997
|
+
return {
|
|
998
|
+
id: wire.id,
|
|
999
|
+
event: wire.event,
|
|
1000
|
+
endpointUrl: wire.endpoint_url,
|
|
1001
|
+
isActive: wire.is_active,
|
|
1002
|
+
createdAt: wire.created_at
|
|
1003
|
+
};
|
|
1004
|
+
}
|
|
1005
|
+
function serializeWebhookWrite(params) {
|
|
1006
|
+
const wire = {};
|
|
1007
|
+
if (params.event !== void 0) wire.event = params.event;
|
|
1008
|
+
if (params.endpointUrl !== void 0) wire.endpoint_url = params.endpointUrl;
|
|
1009
|
+
if (params.isActive !== void 0) wire.is_active = params.isActive;
|
|
1010
|
+
return wire;
|
|
1011
|
+
}
|
|
774
1012
|
var DEFAULT_TOLERANCE_SEC = 300;
|
|
775
1013
|
var SIGNATURE_PREFIX = "sha256=";
|
|
776
1014
|
var HEX_DIGEST_RE = /^[0-9a-f]{64}$/i;
|
|
777
1015
|
var WebhooksResource = class {
|
|
1016
|
+
#http;
|
|
1017
|
+
constructor(http) {
|
|
1018
|
+
this.#http = http;
|
|
1019
|
+
}
|
|
1020
|
+
/** Every webhook registered by your account. Not paginated — the API returns them all. */
|
|
1021
|
+
async list() {
|
|
1022
|
+
const wire = await this.#http.request({ method: "GET", path: WEBHOOKS_PATH });
|
|
1023
|
+
return wire.map(deserializeWebhook);
|
|
1024
|
+
}
|
|
1025
|
+
/**
|
|
1026
|
+
* Subscribes an `https` endpoint to one event. An account holds at most one webhook per event,
|
|
1027
|
+
* and the endpoint must resolve only to public addresses — either failing throws
|
|
1028
|
+
* `ValidationError`. Not auto-retryable (SDK-SPEC.md §8, §12).
|
|
1029
|
+
*/
|
|
1030
|
+
async create(params) {
|
|
1031
|
+
const wire = await this.#http.request({
|
|
1032
|
+
method: "POST",
|
|
1033
|
+
path: WEBHOOKS_PATH,
|
|
1034
|
+
body: serializeWebhookWrite(params)
|
|
1035
|
+
});
|
|
1036
|
+
return deserializeWebhook(wire);
|
|
1037
|
+
}
|
|
1038
|
+
/** Retrieves one of your own webhooks by id (`whk_…`). */
|
|
1039
|
+
async retrieve(id) {
|
|
1040
|
+
assertPathId(id, "webhooks.retrieve", RESERVED_SEGMENTS);
|
|
1041
|
+
const wire = await this.#http.request({
|
|
1042
|
+
method: "GET",
|
|
1043
|
+
path: `${WEBHOOKS_PATH}/${encodeURIComponent(id)}`
|
|
1044
|
+
});
|
|
1045
|
+
return deserializeWebhook(wire);
|
|
1046
|
+
}
|
|
1047
|
+
/**
|
|
1048
|
+
* Overwrites a webhook's event, endpoint and active flag (`PUT`). `event` and `endpointUrl` are
|
|
1049
|
+
* both required; to change one field on its own, use {@link WebhooksResource.update}. Not
|
|
1050
|
+
* auto-retryable (SDK-SPEC.md §8, §12).
|
|
1051
|
+
*/
|
|
1052
|
+
async replace(id, params) {
|
|
1053
|
+
assertPathId(id, "webhooks.replace", RESERVED_SEGMENTS);
|
|
1054
|
+
const wire = await this.#http.request({
|
|
1055
|
+
method: "PUT",
|
|
1056
|
+
path: `${WEBHOOKS_PATH}/${encodeURIComponent(id)}`,
|
|
1057
|
+
body: serializeWebhookWrite(params)
|
|
1058
|
+
});
|
|
1059
|
+
return deserializeWebhook(wire);
|
|
1060
|
+
}
|
|
1061
|
+
/**
|
|
1062
|
+
* Changes only the fields you send (`PATCH`) — e.g. `{ isActive: false }` pauses deliveries
|
|
1063
|
+
* without deleting the webhook. Not auto-retryable (SDK-SPEC.md §8, §12).
|
|
1064
|
+
*/
|
|
1065
|
+
async update(id, params) {
|
|
1066
|
+
assertPathId(id, "webhooks.update", RESERVED_SEGMENTS);
|
|
1067
|
+
const wire = await this.#http.request({
|
|
1068
|
+
method: "PATCH",
|
|
1069
|
+
path: `${WEBHOOKS_PATH}/${encodeURIComponent(id)}`,
|
|
1070
|
+
body: serializeWebhookWrite(params)
|
|
1071
|
+
});
|
|
1072
|
+
return deserializeWebhook(wire);
|
|
1073
|
+
}
|
|
1074
|
+
/** Removes a webhook. Past delivery records are kept for debugging. Not auto-retryable (SDK-SPEC.md §8, §12). */
|
|
1075
|
+
async delete(id) {
|
|
1076
|
+
assertPathId(id, "webhooks.delete", RESERVED_SEGMENTS);
|
|
1077
|
+
await this.#http.request({
|
|
1078
|
+
method: "DELETE",
|
|
1079
|
+
path: `${WEBHOOKS_PATH}/${encodeURIComponent(id)}`
|
|
1080
|
+
});
|
|
1081
|
+
}
|
|
1082
|
+
/**
|
|
1083
|
+
* Returns the account's signing secret — the `secret` to pass to {@link WebhooksResource.verify}.
|
|
1084
|
+
* The API creates it on the first call; it can't be rotated through the API. Treat it like a
|
|
1085
|
+
* password: never log it.
|
|
1086
|
+
*/
|
|
1087
|
+
async retrieveSecret() {
|
|
1088
|
+
const wire = await this.#http.request({
|
|
1089
|
+
method: "GET",
|
|
1090
|
+
path: `${WEBHOOKS_PATH}/secret`
|
|
1091
|
+
});
|
|
1092
|
+
return { signingSecret: wire.signing_secret };
|
|
1093
|
+
}
|
|
1094
|
+
/**
|
|
1095
|
+
* Queues a signed test delivery to the webhook's endpoint so you can check your receiver. It
|
|
1096
|
+
* resolves once the job is queued; the delivery itself arrives asynchronously. Note a test
|
|
1097
|
+
* delivery's body differs from a real event's (fields under `data`) — use it to check
|
|
1098
|
+
* `verify()`, not your payload parsing. Not auto-retryable (SDK-SPEC.md §8, §12).
|
|
1099
|
+
*/
|
|
1100
|
+
async testDelivery(id) {
|
|
1101
|
+
assertPathId(id, "webhooks.testDelivery", RESERVED_SEGMENTS);
|
|
1102
|
+
await this.#http.request({
|
|
1103
|
+
method: "POST",
|
|
1104
|
+
path: `${WEBHOOKS_PATH}/${encodeURIComponent(id)}/test-delivery`
|
|
1105
|
+
});
|
|
1106
|
+
}
|
|
778
1107
|
/**
|
|
779
1108
|
* Verifies an inbound webhook delivery's signature. Returns `false` for any failure mode —
|
|
780
1109
|
* malformed signature, expired timestamp, or a genuine mismatch — never throws, so a caller
|
|
@@ -824,7 +1153,8 @@ var SuqoClient = class {
|
|
|
824
1153
|
this.products = new ProductsResource(http);
|
|
825
1154
|
this.subscriptions = new SubscriptionsResource(http);
|
|
826
1155
|
this.customers = new CustomersResource(http);
|
|
827
|
-
this.
|
|
1156
|
+
this.checkoutSessions = new CheckoutSessionsResource(http);
|
|
1157
|
+
this.webhooks = new WebhooksResource(http);
|
|
828
1158
|
}
|
|
829
1159
|
/** `"sandbox" | "live"` — inferred from the key prefix, never selected explicitly (SDK-SPEC.md §2). */
|
|
830
1160
|
get environment() {
|
|
@@ -853,12 +1183,13 @@ var SuqoClient = class {
|
|
|
853
1183
|
};
|
|
854
1184
|
|
|
855
1185
|
// src/index.ts
|
|
856
|
-
var VERSION = "
|
|
1186
|
+
var VERSION = "2.0.0";
|
|
857
1187
|
|
|
858
1188
|
exports.AuthenticationError = AuthenticationError;
|
|
859
1189
|
exports.KycRequiredError = KycRequiredError;
|
|
860
1190
|
exports.NetworkError = NetworkError;
|
|
861
1191
|
exports.NotFoundError = NotFoundError;
|
|
1192
|
+
exports.PermissionDeniedError = PermissionDeniedError;
|
|
862
1193
|
exports.RateLimitError = RateLimitError;
|
|
863
1194
|
exports.ServerError = ServerError;
|
|
864
1195
|
exports.SubscriptionStatus = SubscriptionStatus;
|