@suqo/sdk 1.1.0 → 2.1.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 +334 -50
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +489 -95
- package/dist/index.d.ts +489 -95
- package/dist/index.js +334 -51
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
interface SuqoErrorOptions {
|
|
11
11
|
/** HTTP status code this error was mapped from, if any (absent for `SuqoConfigError`/`NetworkError` — there was no response). */
|
|
12
12
|
status?: number;
|
|
13
|
-
/** The
|
|
13
|
+
/** The response body this error was mapped from, if any: parsed JSON, or the raw text when it wasn't JSON. */
|
|
14
14
|
rawBody?: unknown;
|
|
15
15
|
/**
|
|
16
16
|
* The backend's request id for this call, if the response included one — ties a failure to a
|
|
@@ -40,7 +40,7 @@ interface SuqoErrorOptions {
|
|
|
40
40
|
declare class SuqoError extends Error {
|
|
41
41
|
/** HTTP status code this error was mapped from, if any. */
|
|
42
42
|
readonly status?: number;
|
|
43
|
-
/** The
|
|
43
|
+
/** The response body this error was mapped from, if any: parsed JSON, or the raw text when it wasn't JSON. */
|
|
44
44
|
readonly rawBody?: unknown;
|
|
45
45
|
/** The backend's request id for this call, if one was returned. See {@link SuqoErrorOptions.requestId}. */
|
|
46
46
|
readonly requestId?: string;
|
|
@@ -86,6 +86,21 @@ interface ValidationErrorOptions extends SuqoErrorOptions {
|
|
|
86
86
|
/** Field-keyed validation messages. Empty if the 400 used the `detail` shape instead. */
|
|
87
87
|
fieldErrors?: FieldErrors;
|
|
88
88
|
}
|
|
89
|
+
/**
|
|
90
|
+
* 403 — the key is valid but may not perform this action, for a reason other than KYC (SDK-SPEC.md
|
|
91
|
+
* §7). The API answers with `{ "detail": "…" }` alone, e.g. a key that doesn't belong to the
|
|
92
|
+
* account. A KYC-shaped 403 (with `status_code`) is {@link KycRequiredError} instead.
|
|
93
|
+
*
|
|
94
|
+
* Also thrown for a 403 that isn't JSON at all — usually a firewall in front of the API (e.g.
|
|
95
|
+
* Cloudflare's `error code: 1010`, which blocks some HTTP clients by `User-Agent`). Its message is
|
|
96
|
+
* just `Request failed with status 403`; read {@link SuqoError.rawBody} (the page's text) for the
|
|
97
|
+
* real cause.
|
|
98
|
+
*
|
|
99
|
+
* Named `PermissionDeniedError`, not `PermissionError`: the stem must be identical in every port
|
|
100
|
+
* (SDK Naming Map R2, R6), and `PermissionError` is a Python builtin.
|
|
101
|
+
*/
|
|
102
|
+
declare class PermissionDeniedError extends SuqoError {
|
|
103
|
+
}
|
|
89
104
|
/**
|
|
90
105
|
* 400 — request validation failed (SDK-SPEC.md §7). The API uses two different 400 body shapes;
|
|
91
106
|
* {@link mapHttpError} normalizes both into this one class so consumers rely on `instanceof`,
|
|
@@ -112,12 +127,15 @@ interface RateLimitErrorOptions extends SuqoErrorOptions {
|
|
|
112
127
|
retryAfter?: number;
|
|
113
128
|
}
|
|
114
129
|
/**
|
|
115
|
-
* 429 — rate limited (SDK-SPEC.md §7).
|
|
116
|
-
*
|
|
117
|
-
*
|
|
130
|
+
* 429 — rate limited (SDK-SPEC.md §7, §10). Live on `checkoutSessions.create()`, the API's one
|
|
131
|
+
* rate-limited endpoint (20 sessions a minute per account). That call is a write, so the SDK never
|
|
132
|
+
* retries it on its own — read {@link RateLimitError.retryAfter} and retry yourself.
|
|
118
133
|
*/
|
|
119
134
|
declare class RateLimitError extends SuqoError {
|
|
120
|
-
/**
|
|
135
|
+
/**
|
|
136
|
+
* Suggested backoff in milliseconds, if the API named one: the `Retry-After` header when present,
|
|
137
|
+
* otherwise the wait the API writes into `detail` ("…available in 41 seconds"). Capped at 60 s.
|
|
138
|
+
*/
|
|
121
139
|
readonly retryAfter?: number;
|
|
122
140
|
constructor(message: string, options?: RateLimitErrorOptions);
|
|
123
141
|
}
|
|
@@ -144,9 +162,10 @@ interface HttpErrorInput {
|
|
|
144
162
|
/** The response's HTTP status text, if available — used only for the generic fallback message. */
|
|
145
163
|
statusText?: string;
|
|
146
164
|
/**
|
|
147
|
-
* The
|
|
165
|
+
* The response body: parsed JSON when it parsed, otherwise the raw text. Expected to be one
|
|
148
166
|
* of `openapi.yaml`'s three error shapes (`FieldError`, `DetailError`, `KycError`) — the shape
|
|
149
|
-
* is detected here, never assumed from the status code alone.
|
|
167
|
+
* is detected here, never assumed from the status code alone. A non-JSON body (a proxy/WAF
|
|
168
|
+
* page) gets the generic status message, never a SUQO-specific one.
|
|
150
169
|
*/
|
|
151
170
|
body?: unknown;
|
|
152
171
|
/** The backend's request id for this call, if one was returned (nice-to-have — Ticket 0 item 3). */
|
|
@@ -177,7 +196,12 @@ interface HttpErrorInput {
|
|
|
177
196
|
* ```ts
|
|
178
197
|
* const response = await fetch(url);
|
|
179
198
|
* if (!response.ok) {
|
|
180
|
-
*
|
|
199
|
+
* const text = await response.text();
|
|
200
|
+
* let body: unknown = text || undefined;
|
|
201
|
+
* try {
|
|
202
|
+
* body = JSON.parse(text); // a SUQO error body; a proxy/WAF page stays text
|
|
203
|
+
* } catch {}
|
|
204
|
+
* throw mapHttpError({ status: response.status, body });
|
|
181
205
|
* }
|
|
182
206
|
* ```
|
|
183
207
|
*/
|
|
@@ -303,12 +327,29 @@ interface HttpPatchRequestOptions<TBody = unknown> extends HttpRequestOptionsBas
|
|
|
303
327
|
/** JSON-serializable request body — only the fields being changed. */
|
|
304
328
|
body?: TBody;
|
|
305
329
|
}
|
|
330
|
+
/**
|
|
331
|
+
* Options for a `PUT` request — a full replacement (`webhooks.replace()`). Never retried, like
|
|
332
|
+
* every write (SDK-SPEC.md §8).
|
|
333
|
+
*/
|
|
334
|
+
interface HttpPutRequestOptions<TBody = unknown> extends HttpRequestOptionsBase {
|
|
335
|
+
method: "PUT";
|
|
336
|
+
/** JSON-serializable request body — the complete new representation. */
|
|
337
|
+
body?: TBody;
|
|
338
|
+
}
|
|
339
|
+
/**
|
|
340
|
+
* Options for a `DELETE` request (`webhooks.delete()`). Carries no body. Never retried, like
|
|
341
|
+
* every write (SDK-SPEC.md §8) — the API answers `204` with an empty body, which
|
|
342
|
+
* {@link HttpClient.request} resolves as `undefined`.
|
|
343
|
+
*/
|
|
344
|
+
interface HttpDeleteRequestOptions extends HttpRequestOptionsBase {
|
|
345
|
+
method: "DELETE";
|
|
346
|
+
}
|
|
306
347
|
/**
|
|
307
348
|
* Options accepted by {@link HttpClient.request}. `HttpClient` itself is internal (not exported
|
|
308
349
|
* from `src/index.ts`); the SDK's actual typed, consumer-facing contract lives one layer up, in
|
|
309
350
|
* each resource method's own public signature.
|
|
310
351
|
*/
|
|
311
|
-
type HttpRequestOptions<TBody = unknown> = HttpGetRequestOptions | HttpPostRequestOptions<TBody> | HttpPatchRequestOptions<TBody
|
|
352
|
+
type HttpRequestOptions<TBody = unknown> = HttpGetRequestOptions | HttpPostRequestOptions<TBody> | HttpPatchRequestOptions<TBody> | HttpPutRequestOptions<TBody> | HttpDeleteRequestOptions;
|
|
312
353
|
/** Options accepted by {@link HttpClient}'s constructor. */
|
|
313
354
|
interface HttpClientOptions {
|
|
314
355
|
/**
|
|
@@ -466,6 +507,27 @@ declare function listAll<T>(firstPage: Page<T>, fetchNext: (nextUrl: string) =>
|
|
|
466
507
|
*/
|
|
467
508
|
declare function bridgeAutoPaging<T>(fetchFirstPage: () => Promise<Page<T>>, fetchNext: (nextUrl: string) => Promise<Page<T>>, maxPages?: number): AsyncIterableIterator<T>;
|
|
468
509
|
|
|
510
|
+
/**
|
|
511
|
+
* Wire enums shared by several models. Each is the known values **or** any other string — the
|
|
512
|
+
* same "loose autocomplete" idiom as {@link import("./Subscription.js").SubscriptionStatus}: a
|
|
513
|
+
* value the API adds later still decodes instead of breaking deployed code (SDK Naming Map §9,
|
|
514
|
+
* "decoders must round-trip an unknown value").
|
|
515
|
+
*
|
|
516
|
+
* Internal aliases only — not exported from the package barrel, because the Naming Map registers
|
|
517
|
+
* no public name for them. Fields that use them show the expanded union to callers.
|
|
518
|
+
*
|
|
519
|
+
* @packageDocumentation
|
|
520
|
+
*/
|
|
521
|
+
type Loose = string & {};
|
|
522
|
+
/** Billing cadence. `one_time` is a single purchase, not a cadence (no next billing date). */
|
|
523
|
+
type IntervalType = "day" | "week" | "month" | "year" | "one_time" | Loose;
|
|
524
|
+
/** Whether a VAT percentage is already included in a price or added on top. */
|
|
525
|
+
type VatType = "inclusive" | "exclusive" | Loose;
|
|
526
|
+
/** A product's pricing model. */
|
|
527
|
+
type ProductType = "simple" | "tiered" | Loose;
|
|
528
|
+
/** What a checkout session was opened for. */
|
|
529
|
+
type CheckoutSessionType = "subscription" | "billing" | Loose;
|
|
530
|
+
|
|
469
531
|
/**
|
|
470
532
|
* The `products` resource's model types (`specs/openapi.yaml` `Product`/`Plan`/`BillingPeriod` —
|
|
471
533
|
* SDK-SPEC.md §5). Field names are camelCase per R3; nothing here is renamed from the wire (R5) —
|
|
@@ -473,12 +535,14 @@ declare function bridgeAutoPaging<T>(fetchFirstPage: () => Promise<Page<T>>, fet
|
|
|
473
535
|
*
|
|
474
536
|
* @packageDocumentation
|
|
475
537
|
*/
|
|
538
|
+
|
|
476
539
|
/** VAT configuration for a {@link Product}, if any. */
|
|
477
540
|
interface ProductVat {
|
|
478
541
|
isVatActive: boolean;
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
542
|
+
/** `null` when no VAT type is configured. */
|
|
543
|
+
vatType: VatType | null;
|
|
544
|
+
/** Decimal string (e.g. `"13.00"`), or `null` when none is configured. Never coerced to a number — SDK-SPEC.md §5. */
|
|
545
|
+
vatPercentage: string | null;
|
|
482
546
|
}
|
|
483
547
|
/** One image on a {@link Product} (`openapi.yaml` `ProductImage`). */
|
|
484
548
|
interface ProductImage {
|
|
@@ -491,11 +555,11 @@ interface ProductImage {
|
|
|
491
555
|
interface Product {
|
|
492
556
|
productId: string;
|
|
493
557
|
name: string;
|
|
494
|
-
description: string;
|
|
495
|
-
type:
|
|
558
|
+
description: string | null;
|
|
559
|
+
type: ProductType;
|
|
496
560
|
isActive: boolean;
|
|
497
|
-
termsAndConditions: string;
|
|
498
|
-
featuresAndBenefits: string;
|
|
561
|
+
termsAndConditions: string | null;
|
|
562
|
+
featuresAndBenefits: string | null;
|
|
499
563
|
vat: ProductVat | null;
|
|
500
564
|
/**
|
|
501
565
|
* Ordered images; blank images already excluded server-side. Each is an object, not a bare URL
|
|
@@ -512,7 +576,7 @@ interface Product {
|
|
|
512
576
|
interface Plan {
|
|
513
577
|
planId: string;
|
|
514
578
|
planName: string;
|
|
515
|
-
description: string;
|
|
579
|
+
description: string | null;
|
|
516
580
|
billingPeriods: BillingPeriod[];
|
|
517
581
|
}
|
|
518
582
|
/**
|
|
@@ -522,7 +586,11 @@ interface Plan {
|
|
|
522
586
|
interface BillingPeriod {
|
|
523
587
|
/** Public id — pass this to `subscriptions.create({ pbpId, ... })`. */
|
|
524
588
|
pbpId: string;
|
|
525
|
-
|
|
589
|
+
/**
|
|
590
|
+
* Billing cadence. `one_time` means a single purchase: subscriptions opened on it can't be
|
|
591
|
+
* cancelled, resumed or rescheduled, and are left out of `subscriptions.list()`'s counts.
|
|
592
|
+
*/
|
|
593
|
+
intervalType: IntervalType;
|
|
526
594
|
intervalCount: number;
|
|
527
595
|
label: string;
|
|
528
596
|
/** Decimal string. Never coerced to a number — SDK-SPEC.md §5. */
|
|
@@ -531,8 +599,21 @@ interface BillingPeriod {
|
|
|
531
599
|
isCurrent: boolean;
|
|
532
600
|
isLimited: boolean;
|
|
533
601
|
isArchived: boolean;
|
|
534
|
-
|
|
535
|
-
|
|
602
|
+
offers: Offer[];
|
|
603
|
+
}
|
|
604
|
+
/** A discount on a {@link BillingPeriod} (`openapi.yaml` `Offer`). */
|
|
605
|
+
interface Offer {
|
|
606
|
+
id: string;
|
|
607
|
+
/**
|
|
608
|
+
* Whole units of the billing period's currency (rupees, not paisa). Already applied to
|
|
609
|
+
* {@link BillingPeriod.price} while the offer is active — don't subtract it again.
|
|
610
|
+
*/
|
|
611
|
+
discountAmount: number;
|
|
612
|
+
/** `YYYY-MM-DD`, or `null` for no start bound. */
|
|
613
|
+
startsAt: string | null;
|
|
614
|
+
/** `YYYY-MM-DD`, or `null` for no end bound. */
|
|
615
|
+
validUntil: string | null;
|
|
616
|
+
isActive: boolean;
|
|
536
617
|
}
|
|
537
618
|
|
|
538
619
|
/**
|
|
@@ -663,17 +744,21 @@ declare const SubscriptionStatus: {
|
|
|
663
744
|
* runtime.
|
|
664
745
|
*/
|
|
665
746
|
type SubscriptionStatus = (typeof SubscriptionStatus)[keyof typeof SubscriptionStatus] | (string & {});
|
|
666
|
-
/**
|
|
747
|
+
/**
|
|
748
|
+
* The product summary embedded on a {@link Subscription} (`openapi.yaml` `SubscriptionProduct`) — a
|
|
749
|
+
* summary, not the full {@link import("./Product.js").Product} record. The API may send `null` for
|
|
750
|
+
* any field, and an omitted field also comes back `null`.
|
|
751
|
+
*/
|
|
667
752
|
interface SubscriptionProduct {
|
|
668
|
-
productId: string;
|
|
669
|
-
name: string;
|
|
670
|
-
planName: string;
|
|
753
|
+
productId: string | null;
|
|
754
|
+
name: string | null;
|
|
755
|
+
planName: string | null;
|
|
671
756
|
/** Pass this to `subscriptions.create({ pbpId, ... })`. */
|
|
672
|
-
pbpId: string;
|
|
673
|
-
label: string;
|
|
757
|
+
pbpId: string | null;
|
|
758
|
+
label: string | null;
|
|
674
759
|
/** Decimal string. Never coerced to a number — SDK-SPEC.md §5. */
|
|
675
|
-
price: string;
|
|
676
|
-
currency: string;
|
|
760
|
+
price: string | null;
|
|
761
|
+
currency: string | null;
|
|
677
762
|
}
|
|
678
763
|
/** A seller's subscription (`openapi.yaml` `Subscription`). */
|
|
679
764
|
interface Subscription {
|
|
@@ -752,15 +837,15 @@ interface UpdateBillingCycleParams {
|
|
|
752
837
|
*/
|
|
753
838
|
/** What `customers.create(params)` accepts (`openapi.yaml` `CreateCustomerRequest`, renamed). */
|
|
754
839
|
interface CreateCustomerParams {
|
|
840
|
+
/** Identifies the buyer. Required. Reads back as `buyerEmail`. */
|
|
841
|
+
email: string;
|
|
755
842
|
/**
|
|
756
|
-
*
|
|
757
|
-
*
|
|
758
|
-
*
|
|
843
|
+
* Optional. A Nepali mobile number: 10 digits starting with 96, 97 or 98 — a `+977` country
|
|
844
|
+
* code, a leading 0, spaces and dashes are accepted and stripped server-side. Can't be changed
|
|
845
|
+
* once set. Reads back as `buyerPhone`.
|
|
759
846
|
*/
|
|
760
|
-
phone
|
|
847
|
+
phone?: string;
|
|
761
848
|
fullName?: string;
|
|
762
|
-
/** Reads back as `buyerEmail`. */
|
|
763
|
-
email?: string;
|
|
764
849
|
address?: string;
|
|
765
850
|
}
|
|
766
851
|
/**
|
|
@@ -776,22 +861,143 @@ interface UpdateCustomerParams {
|
|
|
776
861
|
}
|
|
777
862
|
|
|
778
863
|
/**
|
|
779
|
-
*
|
|
780
|
-
* `
|
|
781
|
-
*
|
|
782
|
-
*
|
|
783
|
-
*
|
|
864
|
+
* The `checkoutSessions` resource's model types (`specs/openapi.yaml` `CreateCheckoutSessionRequest`
|
|
865
|
+
* / `CheckoutSessionResponse` / `CheckoutSession` — SDK-SPEC.md §5). Names per SDK Naming Map §5:
|
|
866
|
+
* the request body is `*Params`, nested write shapes are `*Input` (as {@link
|
|
867
|
+
* import("./Customer.js").CustomerInput}), and the response shared by `checkoutSessions.create()`
|
|
868
|
+
* and `subscriptions.renew()` is {@link CheckoutSessionResponse}.
|
|
784
869
|
*
|
|
785
870
|
* @packageDocumentation
|
|
786
871
|
*/
|
|
787
|
-
|
|
788
|
-
|
|
872
|
+
/**
|
|
873
|
+
* A catalogue item: charges an existing billing period at its catalogue price. The plan sets the
|
|
874
|
+
* price and cadence, so none of the partner-priced fields may be sent alongside `pbpId` — the
|
|
875
|
+
* `never` fields make that a compile error rather than an API 400.
|
|
876
|
+
*/
|
|
877
|
+
interface CatalogueItemInput {
|
|
878
|
+
/** Billing period to charge — `products.list()`'s `plan[].billingPeriods[].pbpId`. */
|
|
879
|
+
pbpId: string;
|
|
880
|
+
name?: never;
|
|
881
|
+
amount?: never;
|
|
882
|
+
intervalType?: never;
|
|
883
|
+
intervalCount?: never;
|
|
884
|
+
}
|
|
885
|
+
/** A partner-priced item: charges a price you set, with no billing period behind it. */
|
|
886
|
+
interface PartnerPricedItemInput {
|
|
887
|
+
/** What the buyer sees on the checkout page. */
|
|
888
|
+
name: string;
|
|
889
|
+
/**
|
|
890
|
+
* The exact price to charge, as a decimal string (e.g. `"2500.00"`). Must already include any
|
|
891
|
+
* discount — SUQO charges this number as sent. Never a `number` (SDK-SPEC.md §5).
|
|
892
|
+
*/
|
|
893
|
+
amount: string;
|
|
894
|
+
/** `day`, `week`, `month`, `year` or `one_time`. */
|
|
895
|
+
intervalType: IntervalType;
|
|
896
|
+
/**
|
|
897
|
+
* Cadence multiplier — `1` with `month` bills monthly. 1–1095 for `day`, 1–156 for `week`, 1–36
|
|
898
|
+
* for `month`, 1–3 for `year`; must be `0` for `one_time`.
|
|
899
|
+
*/
|
|
900
|
+
intervalCount: number;
|
|
901
|
+
pbpId?: never;
|
|
902
|
+
}
|
|
903
|
+
/** One item in {@link CreateCheckoutSessionParams.items}: either a catalogue or a partner-priced item, never a mix. */
|
|
904
|
+
type CheckoutItemInput = CatalogueItemInput | PartnerPricedItemInput;
|
|
905
|
+
/** What `checkoutSessions.create(params)` accepts (`openapi.yaml` `CreateCheckoutSessionRequest`, renamed). */
|
|
906
|
+
interface CreateCheckoutSessionParams {
|
|
907
|
+
/**
|
|
908
|
+
* One to ten items. If two resolve to the same product (e.g. two billing periods of one
|
|
909
|
+
* product), only the last is kept — silently, with no error.
|
|
910
|
+
*/
|
|
911
|
+
items: CheckoutItemInput[];
|
|
912
|
+
/** Where the buyer lands after paying. Not proof of payment — learn the outcome from the `checkout.*` webhooks. */
|
|
913
|
+
returnUrl: string;
|
|
914
|
+
/**
|
|
915
|
+
* A `cus_…` already on your account (`customers.create()`). The buyer then goes straight to
|
|
916
|
+
* payment and can't edit their details there. Omit it to have the buyer enter their full name,
|
|
917
|
+
* email, phone and address at checkout.
|
|
918
|
+
*/
|
|
919
|
+
customerId?: string;
|
|
920
|
+
}
|
|
921
|
+
/**
|
|
922
|
+
* The checkout link returned by `checkoutSessions.create()` and `subscriptions.renew()`
|
|
923
|
+
* (`openapi.yaml` `CheckoutSessionResponse`).
|
|
924
|
+
*/
|
|
925
|
+
interface CheckoutSessionResponse {
|
|
926
|
+
/** `cks_…` — also the `session_id` on the `checkout.*` webhooks. */
|
|
927
|
+
publicId: string;
|
|
928
|
+
/** When `checkoutUrl` stops working, about 30 minutes out. Kept as sent (may carry a `+05:45` offset). */
|
|
929
|
+
expiresAt: string;
|
|
930
|
+
/** Send the buyer here. Not proof of payment — wait for `checkout.succeeded`. */
|
|
931
|
+
checkoutUrl: string;
|
|
932
|
+
}
|
|
933
|
+
/** One line of a {@link CheckoutSession} (`openapi.yaml` `CheckoutLineItem`). */
|
|
934
|
+
interface CheckoutLineItem {
|
|
935
|
+
/** The product name for a catalogue item; the name you sent for a partner-priced one. */
|
|
936
|
+
name: string;
|
|
937
|
+
/** Decimal string. Never coerced to a number — SDK-SPEC.md §5. */
|
|
938
|
+
amount: string;
|
|
939
|
+
/** The billing period for a catalogue item; `null` for a partner-priced one. */
|
|
940
|
+
pbpId: string | null;
|
|
941
|
+
currency: string;
|
|
942
|
+
vatType: VatType | null;
|
|
943
|
+
/** Decimal string, or `null`. */
|
|
944
|
+
vatPercentage: string | null;
|
|
945
|
+
/** Decimal string, or `null`. */
|
|
946
|
+
discountAmount: string | null;
|
|
947
|
+
intervalType: IntervalType;
|
|
948
|
+
intervalCount: number;
|
|
949
|
+
/** Human-readable cadence, e.g. `"Monthly"` or `"Every 2 months"`. */
|
|
950
|
+
displayLabel: string;
|
|
951
|
+
currentPeriodEnd: string | null;
|
|
952
|
+
/** `YYYY-MM-DD` — how far a payment now would extend the subscription. */
|
|
953
|
+
extendsTo: string | null;
|
|
954
|
+
/** `YYYY-MM-DD`. */
|
|
955
|
+
nextPaymentDue: string | null;
|
|
956
|
+
/** Catalogue items only. */
|
|
957
|
+
imageUrls?: string[];
|
|
958
|
+
/** Partner-priced items only. */
|
|
959
|
+
planName?: string | null;
|
|
960
|
+
/**
|
|
961
|
+
* The subscription this line pays for — on every item, new purchase or renewal. Absent only on
|
|
962
|
+
* sessions created before the API added it.
|
|
963
|
+
*/
|
|
964
|
+
subscriptionId?: string;
|
|
965
|
+
}
|
|
966
|
+
/** The seller shown on a {@link CheckoutSession} (`openapi.yaml` `CheckoutSeller`). */
|
|
967
|
+
interface CheckoutSeller {
|
|
968
|
+
id: string;
|
|
969
|
+
/** The seller's own contact number — personal data; don't log it. */
|
|
970
|
+
phone: string;
|
|
971
|
+
businessLogo: string | null;
|
|
972
|
+
businessName: string;
|
|
973
|
+
}
|
|
974
|
+
/**
|
|
975
|
+
* An open checkout session, as returned by `checkoutSessions.retrieve()` (`openapi.yaml`
|
|
976
|
+
* `CheckoutSession`). Only an open session can be read: once paid or expired, retrieving it throws
|
|
977
|
+
* `NotFoundError`.
|
|
978
|
+
*/
|
|
979
|
+
interface CheckoutSession {
|
|
980
|
+
publicId: string;
|
|
981
|
+
lineItems: CheckoutLineItem[];
|
|
982
|
+
/** The `cus_…` the session was opened with, or `null` if the buyer enters their own details. */
|
|
983
|
+
customerId: string | null;
|
|
984
|
+
sellerDetails: CheckoutSeller;
|
|
985
|
+
returnUrl: string;
|
|
986
|
+
/** Kept as sent (may carry a `+05:45` offset). */
|
|
987
|
+
expiresAt: string;
|
|
988
|
+
completedAt: string | null;
|
|
989
|
+
isExpired: boolean;
|
|
990
|
+
/**
|
|
991
|
+
* What the session was opened for: `"subscription"` or `"billing"` today, and any value the API
|
|
992
|
+
* adds later. `null` if the API doesn't send it.
|
|
993
|
+
*/
|
|
994
|
+
sessionType: CheckoutSessionType | null;
|
|
789
995
|
}
|
|
790
996
|
|
|
791
997
|
/**
|
|
792
|
-
* The confirmed webhook event payload shapes
|
|
793
|
-
*
|
|
794
|
-
*
|
|
998
|
+
* The confirmed webhook event payload shapes, re-checked on 2026-11-19 against delivery samples
|
|
999
|
+
* captured and shared by the backend team for every event (checkout, renewal, status change and
|
|
1000
|
+
* all four `api_key.*` events).
|
|
795
1001
|
*
|
|
796
1002
|
* Deliberately **snake_case**, unlike every other model in this SDK — `webhooks.verify()`
|
|
797
1003
|
* (Ticket 5) only checks the signature and returns a `boolean`; it never parses the body itself
|
|
@@ -803,32 +1009,61 @@ interface MessageResponse {
|
|
|
803
1009
|
* @packageDocumentation
|
|
804
1010
|
*/
|
|
805
1011
|
/**
|
|
806
|
-
*
|
|
807
|
-
*
|
|
808
|
-
*
|
|
809
|
-
* not because every webhook event SUQO will ever send is guaranteed to carry one. A future event
|
|
810
|
-
* about a different resource (e.g. a customer- or payout-level event) would need its own base, not
|
|
811
|
-
* be forced through this one. SDK Naming Map v1.1 has no coverage of this at all — same gap as the
|
|
812
|
-
* event fields themselves.
|
|
1012
|
+
* One line item on a `checkout.*` event. A catalogue item has a `pbp_id` and `image_urls`; a
|
|
1013
|
+
* partner-priced (inline) item has `pbp_id: null` and `plan_name`. Internal alias — the Naming Map
|
|
1014
|
+
* registers no public name for it.
|
|
813
1015
|
*/
|
|
814
|
-
interface
|
|
815
|
-
|
|
1016
|
+
interface CheckoutEventLineItem {
|
|
1017
|
+
name: string;
|
|
1018
|
+
/** Decimal string. Never coerced to a number — SDK-SPEC.md §9. */
|
|
1019
|
+
amount: string;
|
|
1020
|
+
/** The billing period charged; `null` for a partner-priced item. */
|
|
1021
|
+
pbp_id: string | null;
|
|
1022
|
+
currency: string;
|
|
1023
|
+
vat_type: VatType | null;
|
|
1024
|
+
/** Decimal string, or `null` when no VAT applies. */
|
|
1025
|
+
vat_percentage: string | null;
|
|
1026
|
+
/** Decimal string, or `null` when there is no discount. */
|
|
1027
|
+
discount_amount: string | null;
|
|
1028
|
+
interval_type: IntervalType;
|
|
1029
|
+
interval_count: number;
|
|
1030
|
+
/** Catalogue items only. */
|
|
1031
|
+
image_urls?: string[];
|
|
1032
|
+
/** Partner-priced items only. */
|
|
1033
|
+
plan_name?: string | null;
|
|
1034
|
+
/**
|
|
1035
|
+
* The subscription this item pays for. Every item in a checkout session carries its own —
|
|
1036
|
+
* catalogue or partner-priced, Test or Live. Grant access by this, not a top-level field.
|
|
1037
|
+
* On `checkout.failed` it is a placeholder subscription that never activates (usually reused
|
|
1038
|
+
* if the buyer retries). Optional because payments made before the API added it lack it.
|
|
1039
|
+
*/
|
|
1040
|
+
subscription_id?: string;
|
|
1041
|
+
}
|
|
1042
|
+
/**
|
|
1043
|
+
* Fields shared by both checkout events. **Changed in 2.0.0:** one delivery per checkout
|
|
1044
|
+
* session, keyed by `session_id`, carrying `line_items` — not one per subscription keyed by a
|
|
1045
|
+
* top-level `subscription_id`. Payments taken through the legacy `subscriptions.create()` report
|
|
1046
|
+
* through this same payload.
|
|
1047
|
+
*/
|
|
1048
|
+
interface CheckoutWebhookEventBase {
|
|
1049
|
+
/** The `cks_…` returned as `publicId` when the session was opened — match deliveries back on this. */
|
|
1050
|
+
session_id: string;
|
|
1051
|
+
/** The session total. Decimal string. Never coerced to a number — SDK-SPEC.md §9. */
|
|
1052
|
+
amount: string;
|
|
1053
|
+
/** What the session charged, one entry per item. */
|
|
1054
|
+
line_items: CheckoutEventLineItem[];
|
|
816
1055
|
}
|
|
817
1056
|
/** A successful checkout. `status` is always `"succeeded"` on this event — never anything else. */
|
|
818
|
-
interface CheckoutSucceededEvent extends
|
|
1057
|
+
interface CheckoutSucceededEvent extends CheckoutWebhookEventBase {
|
|
819
1058
|
event: "checkout.succeeded";
|
|
820
|
-
/** Decimal string. Never coerced to a number — SDK-SPEC.md §9. */
|
|
821
|
-
amount: string;
|
|
822
1059
|
status: "succeeded";
|
|
823
1060
|
}
|
|
824
1061
|
/**
|
|
825
|
-
* A failed checkout. `status` is always `"failed"
|
|
826
|
-
* failure reason
|
|
1062
|
+
* A failed checkout — final, after SUQO's own retries. `status` is always `"failed"`; the specific
|
|
1063
|
+
* failure reason is deliberately not in the payload.
|
|
827
1064
|
*/
|
|
828
|
-
interface CheckoutFailedEvent extends
|
|
1065
|
+
interface CheckoutFailedEvent extends CheckoutWebhookEventBase {
|
|
829
1066
|
event: "checkout.failed";
|
|
830
|
-
/** Decimal string. Never coerced to a number — SDK-SPEC.md §9. */
|
|
831
|
-
amount: string;
|
|
832
1067
|
status: "failed";
|
|
833
1068
|
}
|
|
834
1069
|
/**
|
|
@@ -837,8 +1072,9 @@ interface CheckoutFailedEvent extends SubscriptionWebhookEventBase {
|
|
|
837
1072
|
* §9's prose still says `subscription.status.change`; that's the doc that's stale, not this type
|
|
838
1073
|
* (docs/implementation-plan.md Ticket 0 item 2).
|
|
839
1074
|
*/
|
|
840
|
-
interface SubscriptionStatusChangedEvent
|
|
1075
|
+
interface SubscriptionStatusChangedEvent {
|
|
841
1076
|
event: "subscription.status_changed";
|
|
1077
|
+
subscription_id: string;
|
|
842
1078
|
previous_status: SubscriptionStatus;
|
|
843
1079
|
current_status: SubscriptionStatus;
|
|
844
1080
|
/** ISO 8601 timestamp. */
|
|
@@ -851,8 +1087,11 @@ interface ApiKeyWebhookEventBase {
|
|
|
851
1087
|
name: string;
|
|
852
1088
|
/** Never the real key — always pre-masked by the backend (e.g. `"su_key_ca9...bf9e"`). */
|
|
853
1089
|
masked_key: string;
|
|
854
|
-
/**
|
|
855
|
-
|
|
1090
|
+
/**
|
|
1091
|
+
* `YYYY-MM-DD`, date-only — no time component, unlike `created_at`/`deleted_at`. `null` for a key
|
|
1092
|
+
* created without an expiry.
|
|
1093
|
+
*/
|
|
1094
|
+
expires_at: string | null;
|
|
856
1095
|
/** ISO 8601 timestamp. */
|
|
857
1096
|
created_at: string;
|
|
858
1097
|
}
|
|
@@ -887,6 +1126,77 @@ type WebhookEvent = CheckoutSucceededEvent | CheckoutFailedEvent | SubscriptionS
|
|
|
887
1126
|
*/
|
|
888
1127
|
type WebhookEventType = WebhookEvent["event"];
|
|
889
1128
|
|
|
1129
|
+
/**
|
|
1130
|
+
* The webhook-management model types (`specs/openapi.yaml` `Webhook` / `CreateWebhookRequest` /
|
|
1131
|
+
* `ReplaceWebhookRequest` / `UpdateWebhookRequest` / `WebhookSecret` — SDK-SPEC.md §5, §9).
|
|
1132
|
+
* These describe *registrations* — which endpoint receives which event. The deliveries themselves
|
|
1133
|
+
* are typed in `./WebhookEvent.js`.
|
|
1134
|
+
*
|
|
1135
|
+
* @packageDocumentation
|
|
1136
|
+
*/
|
|
1137
|
+
/**
|
|
1138
|
+
* A known {@link WebhookEventType} with autocomplete, or any other event name — so a {@link
|
|
1139
|
+
* Webhook.event} read back can be written back as-is, and an event the API adds after this SDK
|
|
1140
|
+
* release can still be registered.
|
|
1141
|
+
*/
|
|
1142
|
+
type WebhookEventName = WebhookEventType | (string & {});
|
|
1143
|
+
/** A webhook registration (`openapi.yaml` `Webhook`). One per event per account. */
|
|
1144
|
+
interface Webhook {
|
|
1145
|
+
/** `whk_…` */
|
|
1146
|
+
id: string;
|
|
1147
|
+
/** The event this endpoint receives — a known {@link WebhookEventType}, or a newer one the SDK doesn't know yet. */
|
|
1148
|
+
event: WebhookEventName;
|
|
1149
|
+
endpointUrl: string;
|
|
1150
|
+
/** `false` while deliveries are paused. */
|
|
1151
|
+
isActive: boolean;
|
|
1152
|
+
createdAt: string;
|
|
1153
|
+
}
|
|
1154
|
+
/** What `webhooks.create(params)` accepts (`openapi.yaml` `CreateWebhookRequest`, renamed). */
|
|
1155
|
+
interface CreateWebhookParams {
|
|
1156
|
+
/** One webhook per event per account — a second for the same event is a `ValidationError`. */
|
|
1157
|
+
event: WebhookEventName;
|
|
1158
|
+
/** Must be `https` and resolve only to public addresses. */
|
|
1159
|
+
endpointUrl: string;
|
|
1160
|
+
isActive?: boolean;
|
|
1161
|
+
}
|
|
1162
|
+
/**
|
|
1163
|
+
* What `webhooks.replace(id, params)` accepts (`openapi.yaml` `ReplaceWebhookRequest`, renamed) —
|
|
1164
|
+
* a full overwrite (`PUT`): `event` and `endpointUrl` are both required. To change one field on
|
|
1165
|
+
* its own, use `webhooks.update()`.
|
|
1166
|
+
*/
|
|
1167
|
+
interface ReplaceWebhookParams {
|
|
1168
|
+
event: WebhookEventName;
|
|
1169
|
+
endpointUrl: string;
|
|
1170
|
+
isActive?: boolean;
|
|
1171
|
+
}
|
|
1172
|
+
/**
|
|
1173
|
+
* What `webhooks.update(id, params)` accepts (`openapi.yaml` `UpdateWebhookRequest`, renamed) — a
|
|
1174
|
+
* partial update (`PATCH`): send only what changes, e.g. `{ isActive: false }` to pause deliveries.
|
|
1175
|
+
*/
|
|
1176
|
+
interface UpdateWebhookParams {
|
|
1177
|
+
event?: WebhookEventName;
|
|
1178
|
+
endpointUrl?: string;
|
|
1179
|
+
isActive?: boolean;
|
|
1180
|
+
}
|
|
1181
|
+
/** What `webhooks.retrieveSecret()` returns (`openapi.yaml` `WebhookSecret`). */
|
|
1182
|
+
interface WebhookSecret {
|
|
1183
|
+
/** `whsec_…` — pass it as `secret` to `webhooks.verify()`. Treat it like a password: never log it. */
|
|
1184
|
+
signingSecret: string;
|
|
1185
|
+
}
|
|
1186
|
+
|
|
1187
|
+
/**
|
|
1188
|
+
* What `subscriptions.cancel()`, `subscriptions.updateBillingCycle()`, and
|
|
1189
|
+
* `subscriptions.resume()` all return (`specs/openapi.yaml` `Message`, renamed). Named
|
|
1190
|
+
* `MessageResponse`, not `Message` — SDK Naming Map v1.1 §12: `Message` collides with the
|
|
1191
|
+
* `message` property every {@link import("../errors/SuqoError.js").SuqoError} subclass already
|
|
1192
|
+
* carries.
|
|
1193
|
+
*
|
|
1194
|
+
* @packageDocumentation
|
|
1195
|
+
*/
|
|
1196
|
+
interface MessageResponse {
|
|
1197
|
+
message: string;
|
|
1198
|
+
}
|
|
1199
|
+
|
|
890
1200
|
/**
|
|
891
1201
|
* `client.products` (SDK-SPEC.md §5, §6; `openapi.yaml` `listProducts`). The only resource that
|
|
892
1202
|
* works before KYC verification — no `KycRequiredError` case to handle here.
|
|
@@ -906,10 +1216,11 @@ declare class ProductsResource {
|
|
|
906
1216
|
|
|
907
1217
|
/**
|
|
908
1218
|
* `client.subscriptions` (SDK-SPEC.md §5, §6, §7; `openapi.yaml` `listSubscriptions`/
|
|
909
|
-
* `createSubscription`/`cancelSubscription`/`updateBillingCycle
|
|
1219
|
+
* `retrieveSubscription`/`createSubscription`/`cancelSubscription`/`updateBillingCycle`/
|
|
1220
|
+
* `resumeSubscription`/`renewSubscription`).
|
|
910
1221
|
*
|
|
911
|
-
*
|
|
912
|
-
*
|
|
1222
|
+
* One-time purchases (a billing period whose `intervalType` is `one_time`) appear in `list()` but
|
|
1223
|
+
* can't be cancelled, resumed, rescheduled or renewed — those calls throw `ValidationError`.
|
|
913
1224
|
*/
|
|
914
1225
|
declare class SubscriptionsResource {
|
|
915
1226
|
#private;
|
|
@@ -925,13 +1236,21 @@ declare class SubscriptionsResource {
|
|
|
925
1236
|
*/
|
|
926
1237
|
autoPaging(params?: PageParams): AsyncIterableIterator<Subscription>;
|
|
927
1238
|
/**
|
|
1239
|
+
* Retrieves one of your own subscriptions by id. Built from Swagger's schema; not yet checked
|
|
1240
|
+
* against a captured response.
|
|
1241
|
+
*/
|
|
1242
|
+
retrieve(id: string): Promise<Subscription>;
|
|
1243
|
+
/**
|
|
1244
|
+
* **Legacy** — prefer `checkoutSessions.create()`, which takes up to ten items in one payment
|
|
1245
|
+
* and doesn't need a full customer object. Still supported; existing integrations keep working.
|
|
1246
|
+
*
|
|
928
1247
|
* Creates a subscription in `pending_checkout` state and returns a checkout URL for the buyer
|
|
929
1248
|
* to pay (SDK-SPEC.md §5). Redirect the buyer to `checkoutUrl`; the return is **not** proof of
|
|
930
1249
|
* payment — learn the real outcome via the `checkout.succeeded`/`checkout.failed` webhooks.
|
|
931
1250
|
*
|
|
932
|
-
*
|
|
933
|
-
*
|
|
934
|
-
*
|
|
1251
|
+
* `customer.email` identifies the buyer. A buyer may hold only one live recurring subscription
|
|
1252
|
+
* per product: a second one on any billing period of the same product throws `ValidationError`.
|
|
1253
|
+
* To restart an inactive subscription, use `renew()` rather than creating a new one.
|
|
935
1254
|
*
|
|
936
1255
|
* Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
|
|
937
1256
|
*/
|
|
@@ -939,7 +1258,9 @@ declare class SubscriptionsResource {
|
|
|
939
1258
|
/**
|
|
940
1259
|
* Schedules cancellation for the end of the current billing period — **not** immediate
|
|
941
1260
|
* (confirmed with backend 2026-08-17; immediate cancellation is a future capability). Status
|
|
942
|
-
* moves to `pending_cancellation`; the subscription stays active until the period ends.
|
|
1261
|
+
* moves to `pending_cancellation`; the subscription stays active until the period ends. Calling
|
|
1262
|
+
* it on a subscription already cancelled or pending cancellation returns it unchanged, so a
|
|
1263
|
+
* retry by the caller is safe.
|
|
943
1264
|
*
|
|
944
1265
|
* Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
|
|
945
1266
|
*/
|
|
@@ -952,13 +1273,24 @@ declare class SubscriptionsResource {
|
|
|
952
1273
|
*/
|
|
953
1274
|
updateBillingCycle(params: UpdateBillingCycleParams): Promise<MessageResponse>;
|
|
954
1275
|
/**
|
|
955
|
-
*
|
|
956
|
-
*
|
|
957
|
-
*
|
|
1276
|
+
* Undoes a scheduled cancellation and returns the subscription to `active`. An already-active
|
|
1277
|
+
* subscription is returned unchanged. Once a subscription is `cancelled` there is nothing to
|
|
1278
|
+
* resume — use `renew()`.
|
|
958
1279
|
*
|
|
959
1280
|
* Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
|
|
960
1281
|
*/
|
|
961
1282
|
resume(id: string): Promise<MessageResponse>;
|
|
1283
|
+
/**
|
|
1284
|
+
* Opens a checkout session for the next payment on one of your own subscriptions, reusing its
|
|
1285
|
+
* customer and billing period (or partner-priced item) rather than resubmitting them — how an
|
|
1286
|
+
* inactive subscription is restarted. Send the buyer to the returned `checkoutUrl`, and learn
|
|
1287
|
+
* the outcome from the `checkout.*` webhooks, matched on `publicId`.
|
|
1288
|
+
*
|
|
1289
|
+
* A cancelled or archived subscription, or a paid one-time purchase, can't be renewed: that
|
|
1290
|
+
* throws `ValidationError`. Not auto-retryable — writes never retry until idempotency ships
|
|
1291
|
+
* (SDK-SPEC.md §8, §12).
|
|
1292
|
+
*/
|
|
1293
|
+
renew(subscriptionId: string): Promise<CheckoutSessionResponse>;
|
|
962
1294
|
}
|
|
963
1295
|
|
|
964
1296
|
/**
|
|
@@ -983,14 +1315,15 @@ declare class CustomersResource {
|
|
|
983
1315
|
*/
|
|
984
1316
|
retrieve(id: string): Promise<Customer>;
|
|
985
1317
|
/**
|
|
986
|
-
* Records a customer on the seller's account without opening a subscription. `
|
|
987
|
-
* the buyer;
|
|
988
|
-
* sellers.
|
|
1318
|
+
* Records a customer on the seller's account without opening a subscription. `email` identifies
|
|
1319
|
+
* the buyer and is required; `phone` is optional. The name and address are the seller's own copy
|
|
1320
|
+
* and aren't shared with other sellers. Pass the returned `id` to `checkoutSessions.create()` as
|
|
1321
|
+
* `customerId` to send the buyer straight to payment.
|
|
989
1322
|
*
|
|
990
|
-
*
|
|
991
|
-
* one (the API answers `200` rather than `201`; both resolve to the `Customer` here).
|
|
992
|
-
* this call safe for the caller to retry — but, like every write, the SDK never
|
|
993
|
-
* automatically (SDK-SPEC.md §8, §12).
|
|
1323
|
+
* An email or phone the seller already holds updates that existing customer instead of creating
|
|
1324
|
+
* a second one (the API answers `200` rather than `201`; both resolve to the `Customer` here).
|
|
1325
|
+
* That makes this call safe for the caller to retry — but, like every write, the SDK never
|
|
1326
|
+
* retries it automatically (SDK-SPEC.md §8, §12).
|
|
994
1327
|
*/
|
|
995
1328
|
create(params: CreateCustomerParams): Promise<Customer>;
|
|
996
1329
|
/**
|
|
@@ -1003,13 +1336,32 @@ declare class CustomersResource {
|
|
|
1003
1336
|
}
|
|
1004
1337
|
|
|
1005
1338
|
/**
|
|
1006
|
-
* `client.
|
|
1007
|
-
*
|
|
1008
|
-
*
|
|
1009
|
-
* event body itself (see `models/WebhookEvent.ts` for why the event types stay snake_case).
|
|
1010
|
-
*
|
|
1011
|
-
* @packageDocumentation
|
|
1339
|
+
* `client.checkoutSessions` (SDK-SPEC.md §5; `openapi.yaml` `createCheckoutSession`/
|
|
1340
|
+
* `retrieveCheckoutSession`). The recommended way to collect payment: up to ten items in one
|
|
1341
|
+
* checkout, replacing the legacy `subscriptions.create()`.
|
|
1012
1342
|
*/
|
|
1343
|
+
declare class CheckoutSessionsResource {
|
|
1344
|
+
#private;
|
|
1345
|
+
constructor(http: HttpClient);
|
|
1346
|
+
/**
|
|
1347
|
+
* Opens a checkout session for one to ten items and returns a URL for the buyer to pay. Prices
|
|
1348
|
+
* are snapshotted now, so a plan edited later can't change what the buyer was shown. Redirect
|
|
1349
|
+
* the buyer to `checkoutUrl`; the return to `returnUrl` is **not** proof of payment — learn the
|
|
1350
|
+
* outcome from `checkout.succeeded`/`checkout.failed`, matched on `publicId` (`session_id`).
|
|
1351
|
+
*
|
|
1352
|
+
* The API's one rate-limited endpoint: 20 sessions a minute per account. Past that it throws
|
|
1353
|
+
* `RateLimitError` with `retryAfter` set. Never retried automatically — writes don't retry until
|
|
1354
|
+
* idempotency ships (SDK-SPEC.md §8, §12) — so open a session when the buyer commits to paying,
|
|
1355
|
+
* not on page load.
|
|
1356
|
+
*/
|
|
1357
|
+
create(params: CreateCheckoutSessionParams): Promise<CheckoutSessionResponse>;
|
|
1358
|
+
/**
|
|
1359
|
+
* Reads one of your own open sessions: its line items, customer, seller and expiry. Once paid,
|
|
1360
|
+
* expired, unknown or someone else's, it throws `NotFoundError`.
|
|
1361
|
+
*/
|
|
1362
|
+
retrieve(id: string): Promise<CheckoutSession>;
|
|
1363
|
+
}
|
|
1364
|
+
|
|
1013
1365
|
/** Options accepted by {@link WebhooksResource.verify}. */
|
|
1014
1366
|
interface VerifyWebhookOptions {
|
|
1015
1367
|
/**
|
|
@@ -1033,6 +1385,44 @@ interface VerifyWebhookOptions {
|
|
|
1033
1385
|
toleranceSec?: number;
|
|
1034
1386
|
}
|
|
1035
1387
|
declare class WebhooksResource {
|
|
1388
|
+
#private;
|
|
1389
|
+
constructor(http: HttpClient);
|
|
1390
|
+
/** Every webhook registered by your account. Not paginated — the API returns them all. */
|
|
1391
|
+
list(): Promise<Webhook[]>;
|
|
1392
|
+
/**
|
|
1393
|
+
* Subscribes an `https` endpoint to one event. An account holds at most one webhook per event,
|
|
1394
|
+
* and the endpoint must resolve only to public addresses — either failing throws
|
|
1395
|
+
* `ValidationError`. Not auto-retryable (SDK-SPEC.md §8, §12).
|
|
1396
|
+
*/
|
|
1397
|
+
create(params: CreateWebhookParams): Promise<Webhook>;
|
|
1398
|
+
/** Retrieves one of your own webhooks by id (`whk_…`). */
|
|
1399
|
+
retrieve(id: string): Promise<Webhook>;
|
|
1400
|
+
/**
|
|
1401
|
+
* Overwrites a webhook's event, endpoint and active flag (`PUT`). `event` and `endpointUrl` are
|
|
1402
|
+
* both required; to change one field on its own, use {@link WebhooksResource.update}. Not
|
|
1403
|
+
* auto-retryable (SDK-SPEC.md §8, §12).
|
|
1404
|
+
*/
|
|
1405
|
+
replace(id: string, params: ReplaceWebhookParams): Promise<Webhook>;
|
|
1406
|
+
/**
|
|
1407
|
+
* Changes only the fields you send (`PATCH`) — e.g. `{ isActive: false }` pauses deliveries
|
|
1408
|
+
* without deleting the webhook. Not auto-retryable (SDK-SPEC.md §8, §12).
|
|
1409
|
+
*/
|
|
1410
|
+
update(id: string, params: UpdateWebhookParams): Promise<Webhook>;
|
|
1411
|
+
/** Removes a webhook. Past delivery records are kept for debugging. Not auto-retryable (SDK-SPEC.md §8, §12). */
|
|
1412
|
+
delete(id: string): Promise<void>;
|
|
1413
|
+
/**
|
|
1414
|
+
* Returns the account's signing secret — the `secret` to pass to {@link WebhooksResource.verify}.
|
|
1415
|
+
* The API creates it on the first call; it can't be rotated through the API. Treat it like a
|
|
1416
|
+
* password: never log it.
|
|
1417
|
+
*/
|
|
1418
|
+
retrieveSecret(): Promise<WebhookSecret>;
|
|
1419
|
+
/**
|
|
1420
|
+
* Queues a signed test delivery to the webhook's endpoint so you can check your receiver. It
|
|
1421
|
+
* resolves once the job is queued; the delivery itself arrives asynchronously. Note a test
|
|
1422
|
+
* delivery's body differs from a real event's (fields under `data`) — use it to check
|
|
1423
|
+
* `verify()`, not your payload parsing. Not auto-retryable (SDK-SPEC.md §8, §12).
|
|
1424
|
+
*/
|
|
1425
|
+
testDelivery(id: string): Promise<void>;
|
|
1036
1426
|
/**
|
|
1037
1427
|
* Verifies an inbound webhook delivery's signature. Returns `false` for any failure mode —
|
|
1038
1428
|
* malformed signature, expired timestamp, or a genuine mismatch — never throws, so a caller
|
|
@@ -1083,10 +1473,9 @@ interface SuqoClientOptions {
|
|
|
1083
1473
|
* else to configure in the common case (SDK-SPEC.md §2). Construction throws `SuqoConfigError`
|
|
1084
1474
|
* immediately on a malformed key, or on a `baseUrl` override that disagrees with the key.
|
|
1085
1475
|
*
|
|
1086
|
-
*
|
|
1087
|
-
* `
|
|
1088
|
-
*
|
|
1089
|
-
* call and needs no key at all (SDK-SPEC.md §9), so it's constructed independently.
|
|
1476
|
+
* Every resource shares this one instance's `HttpClient` — same `baseUrl`/`apiKey`/`timeout`/
|
|
1477
|
+
* `maxRetries` for every call, regardless of which resource makes it. `webhooks.verify()` is the
|
|
1478
|
+
* one method that makes no network call (SDK-SPEC.md §9).
|
|
1090
1479
|
*/
|
|
1091
1480
|
declare class SuqoClient {
|
|
1092
1481
|
#private;
|
|
@@ -1096,7 +1485,12 @@ declare class SuqoClient {
|
|
|
1096
1485
|
readonly subscriptions: SubscriptionsResource;
|
|
1097
1486
|
/** List, retrieve, create and update the seller's customers (SDK-SPEC.md §5, §6). */
|
|
1098
1487
|
readonly customers: CustomersResource;
|
|
1099
|
-
/**
|
|
1488
|
+
/** Open and read checkout sessions — the recommended way to collect payment (SDK-SPEC.md §5). */
|
|
1489
|
+
readonly checkoutSessions: CheckoutSessionsResource;
|
|
1490
|
+
/**
|
|
1491
|
+
* Manage webhook registrations, and verify inbound deliveries (SDK-SPEC.md §5, §9). `verify()`
|
|
1492
|
+
* makes no network call; the management methods do.
|
|
1493
|
+
*/
|
|
1100
1494
|
readonly webhooks: WebhooksResource;
|
|
1101
1495
|
constructor(options: SuqoClientOptions);
|
|
1102
1496
|
/** `"sandbox" | "live"` — inferred from the key prefix, never selected explicitly (SDK-SPEC.md §2). */
|
|
@@ -1118,6 +1512,6 @@ declare class SuqoClient {
|
|
|
1118
1512
|
* @packageDocumentation
|
|
1119
1513
|
*/
|
|
1120
1514
|
/** SDK version, stamped into request headers (keep in sync with package.json). */
|
|
1121
|
-
declare const VERSION = "
|
|
1515
|
+
declare const VERSION = "2.1.0";
|
|
1122
1516
|
|
|
1123
|
-
export { type ApiKeyCreatedEvent, type ApiKeyDeletedEvent, type ApiKeyExpiredEvent, type ApiKeyExpiringSoonEvent, AuthenticationError, type BillingPeriod, type CheckoutFailedEvent, type CheckoutSucceededEvent, type CreateCustomerParams, type CreateSubscriptionParams, type CreateSubscriptionResponse, type Customer, type CustomerInput, type CustomerInputBilling, type CustomerInputShipping, type FieldErrors, type HttpErrorInput, KycRequiredError, type KycRequiredErrorOptions, type MessageResponse, NetworkError, NotFoundError, type Page, type PageParams, type Plan, type Product, type ProductImage, type ProductVat, RateLimitError, type RateLimitErrorOptions, ServerError, type Subscription, type SubscriptionCustomer, type SubscriptionCustomerBilling, type SubscriptionCustomerShipping, type SubscriptionPage, type SubscriptionProduct, SubscriptionStatus, type SubscriptionStatusChangedEvent, type SubscriptionStatusCounts, SuqoClient, type SuqoClientOptions, SuqoConfigError, type SuqoEnvironment, SuqoError, type SuqoErrorOptions, type UpdateBillingCycleParams, type UpdateCustomerParams, VERSION, ValidationError, type ValidationErrorOptions, type VerifyWebhookOptions, type WebhookEvent, type WebhookEventType, bridgeAutoPaging, deserializePage, listAll, mapHttpError, toPageQuery };
|
|
1517
|
+
export { type ApiKeyCreatedEvent, type ApiKeyDeletedEvent, type ApiKeyExpiredEvent, type ApiKeyExpiringSoonEvent, AuthenticationError, type BillingPeriod, type CatalogueItemInput, type CheckoutFailedEvent, type CheckoutItemInput, type CheckoutLineItem, type CheckoutSeller, type CheckoutSession, type CheckoutSessionResponse, type CheckoutSucceededEvent, type CreateCheckoutSessionParams, type CreateCustomerParams, type CreateSubscriptionParams, type CreateSubscriptionResponse, type CreateWebhookParams, type Customer, type CustomerInput, type CustomerInputBilling, type CustomerInputShipping, type FieldErrors, type HttpErrorInput, KycRequiredError, type KycRequiredErrorOptions, type MessageResponse, NetworkError, NotFoundError, type Offer, type Page, type PageParams, type PartnerPricedItemInput, PermissionDeniedError, type Plan, type Product, type ProductImage, type ProductVat, RateLimitError, type RateLimitErrorOptions, type ReplaceWebhookParams, ServerError, type Subscription, type SubscriptionCustomer, type SubscriptionCustomerBilling, type SubscriptionCustomerShipping, type SubscriptionPage, type SubscriptionProduct, SubscriptionStatus, type SubscriptionStatusChangedEvent, type SubscriptionStatusCounts, SuqoClient, type SuqoClientOptions, SuqoConfigError, type SuqoEnvironment, SuqoError, type SuqoErrorOptions, type UpdateBillingCycleParams, type UpdateCustomerParams, type UpdateWebhookParams, VERSION, ValidationError, type ValidationErrorOptions, type VerifyWebhookOptions, type Webhook, type WebhookEvent, type WebhookEventType, type WebhookSecret, bridgeAutoPaging, deserializePage, listAll, mapHttpError, toPageQuery };
|