@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/dist/index.d.cts
CHANGED
|
@@ -48,9 +48,12 @@ declare class SuqoError extends Error {
|
|
|
48
48
|
}
|
|
49
49
|
/**
|
|
50
50
|
* Construction-time configuration problems: a malformed API key, or an explicit `baseUrl`
|
|
51
|
-
* override that disagrees with the key's prefix (SDK-SPEC.md §2, §7).
|
|
52
|
-
*
|
|
53
|
-
* `
|
|
51
|
+
* override that disagrees with the key's prefix (SDK-SPEC.md §2, §7). Also reused for a call-time
|
|
52
|
+
* argument that would otherwise silently corrupt a request rather than reach the API at all — e.g.
|
|
53
|
+
* an empty `customers.retrieve(id)` (#42) — the same "never even attempted" character as a bad
|
|
54
|
+
* construction option. Thrown before any request is made — analogous to a syntax error in the
|
|
55
|
+
* integration, not an HTTP failure. Never carries `status`/`rawBody`; there was no request to map
|
|
56
|
+
* one from.
|
|
54
57
|
*/
|
|
55
58
|
declare class SuqoConfigError extends SuqoError {
|
|
56
59
|
constructor(message: string, options?: {
|
|
@@ -83,6 +86,16 @@ interface ValidationErrorOptions extends SuqoErrorOptions {
|
|
|
83
86
|
/** Field-keyed validation messages. Empty if the 400 used the `detail` shape instead. */
|
|
84
87
|
fieldErrors?: FieldErrors;
|
|
85
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
|
+
* Named `PermissionDeniedError`, not `PermissionError`: the stem must be identical in every port
|
|
95
|
+
* (SDK Naming Map R2, R6), and `PermissionError` is a Python builtin.
|
|
96
|
+
*/
|
|
97
|
+
declare class PermissionDeniedError extends SuqoError {
|
|
98
|
+
}
|
|
86
99
|
/**
|
|
87
100
|
* 400 — request validation failed (SDK-SPEC.md §7). The API uses two different 400 body shapes;
|
|
88
101
|
* {@link mapHttpError} normalizes both into this one class so consumers rely on `instanceof`,
|
|
@@ -109,12 +122,15 @@ interface RateLimitErrorOptions extends SuqoErrorOptions {
|
|
|
109
122
|
retryAfter?: number;
|
|
110
123
|
}
|
|
111
124
|
/**
|
|
112
|
-
* 429 — rate limited (SDK-SPEC.md §7).
|
|
113
|
-
*
|
|
114
|
-
*
|
|
125
|
+
* 429 — rate limited (SDK-SPEC.md §7, §10). Live on `checkoutSessions.create()`, the API's one
|
|
126
|
+
* rate-limited endpoint (20 sessions a minute per account). That call is a write, so the SDK never
|
|
127
|
+
* retries it on its own — read {@link RateLimitError.retryAfter} and retry yourself.
|
|
115
128
|
*/
|
|
116
129
|
declare class RateLimitError extends SuqoError {
|
|
117
|
-
/**
|
|
130
|
+
/**
|
|
131
|
+
* Suggested backoff in milliseconds, if the API named one: the `Retry-After` header when present,
|
|
132
|
+
* otherwise the wait the API writes into `detail` ("…available in 41 seconds"). Capped at 60 s.
|
|
133
|
+
*/
|
|
118
134
|
readonly retryAfter?: number;
|
|
119
135
|
constructor(message: string, options?: RateLimitErrorOptions);
|
|
120
136
|
}
|
|
@@ -291,12 +307,38 @@ interface HttpPostRequestOptions<TBody = unknown> extends HttpRequestOptionsBase
|
|
|
291
307
|
/** JSON-serializable request body. Omit entirely for a bodyless write (e.g. `cancel`). */
|
|
292
308
|
body?: TBody;
|
|
293
309
|
}
|
|
310
|
+
/**
|
|
311
|
+
* Options for a `PATCH` request — a partial update (`customers.update()`). Same body typing as
|
|
312
|
+
* {@link HttpPostRequestOptions}, and like every write it is never retried (SDK-SPEC.md §8).
|
|
313
|
+
*/
|
|
314
|
+
interface HttpPatchRequestOptions<TBody = unknown> extends HttpRequestOptionsBase {
|
|
315
|
+
method: "PATCH";
|
|
316
|
+
/** JSON-serializable request body — only the fields being changed. */
|
|
317
|
+
body?: TBody;
|
|
318
|
+
}
|
|
319
|
+
/**
|
|
320
|
+
* Options for a `PUT` request — a full replacement (`webhooks.replace()`). Never retried, like
|
|
321
|
+
* every write (SDK-SPEC.md §8).
|
|
322
|
+
*/
|
|
323
|
+
interface HttpPutRequestOptions<TBody = unknown> extends HttpRequestOptionsBase {
|
|
324
|
+
method: "PUT";
|
|
325
|
+
/** JSON-serializable request body — the complete new representation. */
|
|
326
|
+
body?: TBody;
|
|
327
|
+
}
|
|
328
|
+
/**
|
|
329
|
+
* Options for a `DELETE` request (`webhooks.delete()`). Carries no body. Never retried, like
|
|
330
|
+
* every write (SDK-SPEC.md §8) — the API answers `204` with an empty body, which
|
|
331
|
+
* {@link HttpClient.request} resolves as `undefined`.
|
|
332
|
+
*/
|
|
333
|
+
interface HttpDeleteRequestOptions extends HttpRequestOptionsBase {
|
|
334
|
+
method: "DELETE";
|
|
335
|
+
}
|
|
294
336
|
/**
|
|
295
337
|
* Options accepted by {@link HttpClient.request}. `HttpClient` itself is internal (not exported
|
|
296
338
|
* from `src/index.ts`); the SDK's actual typed, consumer-facing contract lives one layer up, in
|
|
297
339
|
* each resource method's own public signature.
|
|
298
340
|
*/
|
|
299
|
-
type HttpRequestOptions<TBody = unknown> = HttpGetRequestOptions | HttpPostRequestOptions<TBody
|
|
341
|
+
type HttpRequestOptions<TBody = unknown> = HttpGetRequestOptions | HttpPostRequestOptions<TBody> | HttpPatchRequestOptions<TBody> | HttpPutRequestOptions<TBody> | HttpDeleteRequestOptions;
|
|
300
342
|
/** Options accepted by {@link HttpClient}'s constructor. */
|
|
301
343
|
interface HttpClientOptions {
|
|
302
344
|
/**
|
|
@@ -454,6 +496,27 @@ declare function listAll<T>(firstPage: Page<T>, fetchNext: (nextUrl: string) =>
|
|
|
454
496
|
*/
|
|
455
497
|
declare function bridgeAutoPaging<T>(fetchFirstPage: () => Promise<Page<T>>, fetchNext: (nextUrl: string) => Promise<Page<T>>, maxPages?: number): AsyncIterableIterator<T>;
|
|
456
498
|
|
|
499
|
+
/**
|
|
500
|
+
* Wire enums shared by several models. Each is the known values **or** any other string — the
|
|
501
|
+
* same "loose autocomplete" idiom as {@link import("./Subscription.js").SubscriptionStatus}: a
|
|
502
|
+
* value the API adds later still decodes instead of breaking deployed code (SDK Naming Map §9,
|
|
503
|
+
* "decoders must round-trip an unknown value").
|
|
504
|
+
*
|
|
505
|
+
* Internal aliases only — not exported from the package barrel, because the Naming Map registers
|
|
506
|
+
* no public name for them. Fields that use them show the expanded union to callers.
|
|
507
|
+
*
|
|
508
|
+
* @packageDocumentation
|
|
509
|
+
*/
|
|
510
|
+
type Loose = string & {};
|
|
511
|
+
/** Billing cadence. `one_time` is a single purchase, not a cadence (no next billing date). */
|
|
512
|
+
type IntervalType = "day" | "week" | "month" | "year" | "one_time" | Loose;
|
|
513
|
+
/** Whether a VAT percentage is already included in a price or added on top. */
|
|
514
|
+
type VatType = "inclusive" | "exclusive" | Loose;
|
|
515
|
+
/** A product's pricing model. */
|
|
516
|
+
type ProductType = "simple" | "tiered" | Loose;
|
|
517
|
+
/** What a checkout session was opened for. */
|
|
518
|
+
type CheckoutSessionType = "subscription" | "billing" | Loose;
|
|
519
|
+
|
|
457
520
|
/**
|
|
458
521
|
* The `products` resource's model types (`specs/openapi.yaml` `Product`/`Plan`/`BillingPeriod` —
|
|
459
522
|
* SDK-SPEC.md §5). Field names are camelCase per R3; nothing here is renamed from the wire (R5) —
|
|
@@ -461,25 +524,37 @@ declare function bridgeAutoPaging<T>(fetchFirstPage: () => Promise<Page<T>>, fet
|
|
|
461
524
|
*
|
|
462
525
|
* @packageDocumentation
|
|
463
526
|
*/
|
|
527
|
+
|
|
464
528
|
/** VAT configuration for a {@link Product}, if any. */
|
|
465
529
|
interface ProductVat {
|
|
466
530
|
isVatActive: boolean;
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
531
|
+
/** `null` when no VAT type is configured. */
|
|
532
|
+
vatType: VatType | null;
|
|
533
|
+
/** Decimal string (e.g. `"13.00"`), or `null` when none is configured. Never coerced to a number — SDK-SPEC.md §5. */
|
|
534
|
+
vatPercentage: string | null;
|
|
535
|
+
}
|
|
536
|
+
/** One image on a {@link Product} (`openapi.yaml` `ProductImage`). */
|
|
537
|
+
interface ProductImage {
|
|
538
|
+
/** Absolute image URL. */
|
|
539
|
+
image: string;
|
|
540
|
+
/** Display position, lowest first. */
|
|
541
|
+
imageOrder: number;
|
|
470
542
|
}
|
|
471
543
|
/** A seller's product, as returned by `products.list()` (`openapi.yaml` `Product`). */
|
|
472
544
|
interface Product {
|
|
473
545
|
productId: string;
|
|
474
546
|
name: string;
|
|
475
|
-
description: string;
|
|
476
|
-
type:
|
|
547
|
+
description: string | null;
|
|
548
|
+
type: ProductType;
|
|
477
549
|
isActive: boolean;
|
|
478
|
-
termsAndConditions: string;
|
|
479
|
-
featuresAndBenefits: string;
|
|
550
|
+
termsAndConditions: string | null;
|
|
551
|
+
featuresAndBenefits: string | null;
|
|
480
552
|
vat: ProductVat | null;
|
|
481
|
-
/**
|
|
482
|
-
|
|
553
|
+
/**
|
|
554
|
+
* Ordered images; blank images already excluded server-side. Each is an object, not a bare URL
|
|
555
|
+
* string — the API has always sent `{ image, image_order }`.
|
|
556
|
+
*/
|
|
557
|
+
productImage: ProductImage[];
|
|
483
558
|
plan: Plan[];
|
|
484
559
|
/** Count of active subscribers. Sent as a string on the wire — kept as one, never coerced (SDK-SPEC.md §5). */
|
|
485
560
|
totalSubscribers: string;
|
|
@@ -490,7 +565,7 @@ interface Product {
|
|
|
490
565
|
interface Plan {
|
|
491
566
|
planId: string;
|
|
492
567
|
planName: string;
|
|
493
|
-
description: string;
|
|
568
|
+
description: string | null;
|
|
494
569
|
billingPeriods: BillingPeriod[];
|
|
495
570
|
}
|
|
496
571
|
/**
|
|
@@ -500,7 +575,11 @@ interface Plan {
|
|
|
500
575
|
interface BillingPeriod {
|
|
501
576
|
/** Public id — pass this to `subscriptions.create({ pbpId, ... })`. */
|
|
502
577
|
pbpId: string;
|
|
503
|
-
|
|
578
|
+
/**
|
|
579
|
+
* Billing cadence. `one_time` means a single purchase: subscriptions opened on it can't be
|
|
580
|
+
* cancelled, resumed or rescheduled, and are left out of `subscriptions.list()`'s counts.
|
|
581
|
+
*/
|
|
582
|
+
intervalType: IntervalType;
|
|
504
583
|
intervalCount: number;
|
|
505
584
|
label: string;
|
|
506
585
|
/** Decimal string. Never coerced to a number — SDK-SPEC.md §5. */
|
|
@@ -509,8 +588,21 @@ interface BillingPeriod {
|
|
|
509
588
|
isCurrent: boolean;
|
|
510
589
|
isLimited: boolean;
|
|
511
590
|
isArchived: boolean;
|
|
512
|
-
|
|
513
|
-
|
|
591
|
+
offers: Offer[];
|
|
592
|
+
}
|
|
593
|
+
/** A discount on a {@link BillingPeriod} (`openapi.yaml` `Offer`). */
|
|
594
|
+
interface Offer {
|
|
595
|
+
id: string;
|
|
596
|
+
/**
|
|
597
|
+
* Whole units of the billing period's currency (rupees, not paisa). Already applied to
|
|
598
|
+
* {@link BillingPeriod.price} while the offer is active — don't subtract it again.
|
|
599
|
+
*/
|
|
600
|
+
discountAmount: number;
|
|
601
|
+
/** `YYYY-MM-DD`, or `null` for no start bound. */
|
|
602
|
+
startsAt: string | null;
|
|
603
|
+
/** `YYYY-MM-DD`, or `null` for no end bound. */
|
|
604
|
+
validUntil: string | null;
|
|
605
|
+
isActive: boolean;
|
|
514
606
|
}
|
|
515
607
|
|
|
516
608
|
/**
|
|
@@ -589,18 +681,19 @@ interface CustomerInput {
|
|
|
589
681
|
}
|
|
590
682
|
/**
|
|
591
683
|
* A seller's own customer record, as returned by `customers.list()`/`customers.retrieve()`
|
|
592
|
-
* (`openapi.yaml` `Customer
|
|
593
|
-
*
|
|
684
|
+
* (`openapi.yaml` `Customer`). Distinct from {@link SubscriptionCustomer} and {@link CustomerInput}
|
|
685
|
+
* — see this file's module doc.
|
|
594
686
|
*
|
|
595
687
|
* Uses `buyer*`-prefixed field names, not the `client.*` nesting Subscriptions uses — a genuinely
|
|
596
|
-
* different resource with its own
|
|
688
|
+
* different resource with its own convention, carried through as-is.
|
|
597
689
|
*/
|
|
598
690
|
interface Customer {
|
|
599
|
-
/**
|
|
600
|
-
id:
|
|
691
|
+
/** Opaque prefixed id, e.g. `"cus_1ce18d624"` — a string, like `pbp_...` on billing periods, not an integer. */
|
|
692
|
+
id: string;
|
|
601
693
|
buyerPhone: string | null;
|
|
602
694
|
buyerEmail: string | null;
|
|
603
695
|
fullName: string | null;
|
|
696
|
+
address: string | null;
|
|
604
697
|
createdAt: string;
|
|
605
698
|
}
|
|
606
699
|
|
|
@@ -640,17 +733,21 @@ declare const SubscriptionStatus: {
|
|
|
640
733
|
* runtime.
|
|
641
734
|
*/
|
|
642
735
|
type SubscriptionStatus = (typeof SubscriptionStatus)[keyof typeof SubscriptionStatus] | (string & {});
|
|
643
|
-
/**
|
|
736
|
+
/**
|
|
737
|
+
* The product summary embedded on a {@link Subscription} (`openapi.yaml` `SubscriptionProduct`) — a
|
|
738
|
+
* summary, not the full {@link import("./Product.js").Product} record. The API may send `null` for
|
|
739
|
+
* any field, and an omitted field also comes back `null`.
|
|
740
|
+
*/
|
|
644
741
|
interface SubscriptionProduct {
|
|
645
|
-
productId: string;
|
|
646
|
-
name: string;
|
|
647
|
-
planName: string;
|
|
742
|
+
productId: string | null;
|
|
743
|
+
name: string | null;
|
|
744
|
+
planName: string | null;
|
|
648
745
|
/** Pass this to `subscriptions.create({ pbpId, ... })`. */
|
|
649
|
-
pbpId: string;
|
|
650
|
-
label: string;
|
|
746
|
+
pbpId: string | null;
|
|
747
|
+
label: string | null;
|
|
651
748
|
/** Decimal string. Never coerced to a number — SDK-SPEC.md §5. */
|
|
652
|
-
price: string;
|
|
653
|
-
currency: string;
|
|
749
|
+
price: string | null;
|
|
750
|
+
currency: string | null;
|
|
654
751
|
}
|
|
655
752
|
/** A seller's subscription (`openapi.yaml` `Subscription`). */
|
|
656
753
|
interface Subscription {
|
|
@@ -717,22 +814,174 @@ interface UpdateBillingCycleParams {
|
|
|
717
814
|
}
|
|
718
815
|
|
|
719
816
|
/**
|
|
720
|
-
*
|
|
721
|
-
* `
|
|
722
|
-
*
|
|
723
|
-
*
|
|
724
|
-
*
|
|
817
|
+
* Input shapes for the `customers` write methods (`specs/openapi.yaml`
|
|
818
|
+
* `CreateCustomerRequest`/`UpdateCustomerRequest`). Named `*Params`, not `*Request` — SDK Naming
|
|
819
|
+
* Map v1.1 §12, same as `subscriptionParams.ts`.
|
|
820
|
+
*
|
|
821
|
+
* Note the read/write name asymmetry on the wire: `phone`/`email` sent here read back on
|
|
822
|
+
* {@link import("./Customer.js").Customer} as `buyerPhone`/`buyerEmail`. The params keep the
|
|
823
|
+
* wire's write-side names rather than borrowing the read side's `buyer*` prefix.
|
|
725
824
|
*
|
|
726
825
|
* @packageDocumentation
|
|
727
826
|
*/
|
|
728
|
-
|
|
729
|
-
|
|
827
|
+
/** What `customers.create(params)` accepts (`openapi.yaml` `CreateCustomerRequest`, renamed). */
|
|
828
|
+
interface CreateCustomerParams {
|
|
829
|
+
/** Identifies the buyer. Required. Reads back as `buyerEmail`. */
|
|
830
|
+
email: string;
|
|
831
|
+
/**
|
|
832
|
+
* Optional. A Nepali mobile number: 10 digits starting with 96, 97 or 98 — a `+977` country
|
|
833
|
+
* code, a leading 0, spaces and dashes are accepted and stripped server-side. Can't be changed
|
|
834
|
+
* once set. Reads back as `buyerPhone`.
|
|
835
|
+
*/
|
|
836
|
+
phone?: string;
|
|
837
|
+
fullName?: string;
|
|
838
|
+
address?: string;
|
|
839
|
+
}
|
|
840
|
+
/**
|
|
841
|
+
* What `customers.update(id, params)` accepts (`openapi.yaml` `UpdateCustomerRequest`, renamed).
|
|
842
|
+
* Send only the fields you're changing; `""` clears a field. There's no `phone` — it identifies
|
|
843
|
+
* the buyer and can't be changed.
|
|
844
|
+
*/
|
|
845
|
+
interface UpdateCustomerParams {
|
|
846
|
+
fullName?: string;
|
|
847
|
+
/** Reads back as `buyerEmail`. */
|
|
848
|
+
email?: string;
|
|
849
|
+
address?: string;
|
|
850
|
+
}
|
|
851
|
+
|
|
852
|
+
/**
|
|
853
|
+
* The `checkoutSessions` resource's model types (`specs/openapi.yaml` `CreateCheckoutSessionRequest`
|
|
854
|
+
* / `CheckoutSessionResponse` / `CheckoutSession` — SDK-SPEC.md §5). Names per SDK Naming Map §5:
|
|
855
|
+
* the request body is `*Params`, nested write shapes are `*Input` (as {@link
|
|
856
|
+
* import("./Customer.js").CustomerInput}), and the response shared by `checkoutSessions.create()`
|
|
857
|
+
* and `subscriptions.renew()` is {@link CheckoutSessionResponse}.
|
|
858
|
+
*
|
|
859
|
+
* @packageDocumentation
|
|
860
|
+
*/
|
|
861
|
+
/**
|
|
862
|
+
* A catalogue item: charges an existing billing period at its catalogue price. The plan sets the
|
|
863
|
+
* price and cadence, so none of the partner-priced fields may be sent alongside `pbpId` — the
|
|
864
|
+
* `never` fields make that a compile error rather than an API 400.
|
|
865
|
+
*/
|
|
866
|
+
interface CatalogueItemInput {
|
|
867
|
+
/** Billing period to charge — `products.list()`'s `plan[].billingPeriods[].pbpId`. */
|
|
868
|
+
pbpId: string;
|
|
869
|
+
name?: never;
|
|
870
|
+
amount?: never;
|
|
871
|
+
intervalType?: never;
|
|
872
|
+
intervalCount?: never;
|
|
873
|
+
}
|
|
874
|
+
/** A partner-priced item: charges a price you set, with no billing period behind it. */
|
|
875
|
+
interface PartnerPricedItemInput {
|
|
876
|
+
/** What the buyer sees on the checkout page. */
|
|
877
|
+
name: string;
|
|
878
|
+
/**
|
|
879
|
+
* The exact price to charge, as a decimal string (e.g. `"2500.00"`). Must already include any
|
|
880
|
+
* discount — SUQO charges this number as sent. Never a `number` (SDK-SPEC.md §5).
|
|
881
|
+
*/
|
|
882
|
+
amount: string;
|
|
883
|
+
/** `day`, `week`, `month`, `year` or `one_time`. */
|
|
884
|
+
intervalType: IntervalType;
|
|
885
|
+
/**
|
|
886
|
+
* Cadence multiplier — `1` with `month` bills monthly. 1–1095 for `day`, 1–156 for `week`, 1–36
|
|
887
|
+
* for `month`, 1–3 for `year`; must be `0` for `one_time`.
|
|
888
|
+
*/
|
|
889
|
+
intervalCount: number;
|
|
890
|
+
pbpId?: never;
|
|
891
|
+
}
|
|
892
|
+
/** One item in {@link CreateCheckoutSessionParams.items}: either a catalogue or a partner-priced item, never a mix. */
|
|
893
|
+
type CheckoutItemInput = CatalogueItemInput | PartnerPricedItemInput;
|
|
894
|
+
/** What `checkoutSessions.create(params)` accepts (`openapi.yaml` `CreateCheckoutSessionRequest`, renamed). */
|
|
895
|
+
interface CreateCheckoutSessionParams {
|
|
896
|
+
/**
|
|
897
|
+
* One to ten items. If two resolve to the same product (e.g. two billing periods of one
|
|
898
|
+
* product), only the last is kept — silently, with no error.
|
|
899
|
+
*/
|
|
900
|
+
items: CheckoutItemInput[];
|
|
901
|
+
/** Where the buyer lands after paying. Not proof of payment — learn the outcome from the `checkout.*` webhooks. */
|
|
902
|
+
returnUrl: string;
|
|
903
|
+
/**
|
|
904
|
+
* A `cus_…` already on your account (`customers.create()`). The buyer then goes straight to
|
|
905
|
+
* payment and can't edit their details there. Omit it to have the buyer enter their full name,
|
|
906
|
+
* email, phone and address at checkout.
|
|
907
|
+
*/
|
|
908
|
+
customerId?: string;
|
|
909
|
+
}
|
|
910
|
+
/**
|
|
911
|
+
* The checkout link returned by `checkoutSessions.create()` and `subscriptions.renew()`
|
|
912
|
+
* (`openapi.yaml` `CheckoutSessionResponse`).
|
|
913
|
+
*/
|
|
914
|
+
interface CheckoutSessionResponse {
|
|
915
|
+
/** `cks_…` — also the `session_id` on the `checkout.*` webhooks. */
|
|
916
|
+
publicId: string;
|
|
917
|
+
/** When `checkoutUrl` stops working, about 30 minutes out. Kept as sent (may carry a `+05:45` offset). */
|
|
918
|
+
expiresAt: string;
|
|
919
|
+
/** Send the buyer here. Not proof of payment — wait for `checkout.succeeded`. */
|
|
920
|
+
checkoutUrl: string;
|
|
921
|
+
}
|
|
922
|
+
/** One line of a {@link CheckoutSession} (`openapi.yaml` `CheckoutLineItem`). */
|
|
923
|
+
interface CheckoutLineItem {
|
|
924
|
+
/** The product name for a catalogue item; the name you sent for a partner-priced one. */
|
|
925
|
+
name: string;
|
|
926
|
+
/** Decimal string. Never coerced to a number — SDK-SPEC.md §5. */
|
|
927
|
+
amount: string;
|
|
928
|
+
/** The billing period for a catalogue item; `null` for a partner-priced one. */
|
|
929
|
+
pbpId: string | null;
|
|
930
|
+
currency: string;
|
|
931
|
+
vatType: VatType | null;
|
|
932
|
+
/** Decimal string, or `null`. */
|
|
933
|
+
vatPercentage: string | null;
|
|
934
|
+
/** Decimal string, or `null`. */
|
|
935
|
+
discountAmount: string | null;
|
|
936
|
+
intervalType: IntervalType;
|
|
937
|
+
intervalCount: number;
|
|
938
|
+
/** Human-readable cadence, e.g. `"Monthly"` or `"Every 2 months"`. */
|
|
939
|
+
displayLabel: string;
|
|
940
|
+
currentPeriodEnd: string | null;
|
|
941
|
+
/** `YYYY-MM-DD` — how far a payment now would extend the subscription. */
|
|
942
|
+
extendsTo: string | null;
|
|
943
|
+
/** `YYYY-MM-DD`. */
|
|
944
|
+
nextPaymentDue: string | null;
|
|
945
|
+
/** Catalogue items only. */
|
|
946
|
+
imageUrls?: string[];
|
|
947
|
+
/** Partner-priced items only. */
|
|
948
|
+
planName?: string | null;
|
|
949
|
+
}
|
|
950
|
+
/** The seller shown on a {@link CheckoutSession} (`openapi.yaml` `CheckoutSeller`). */
|
|
951
|
+
interface CheckoutSeller {
|
|
952
|
+
id: string;
|
|
953
|
+
/** The seller's own contact number — personal data; don't log it. */
|
|
954
|
+
phone: string;
|
|
955
|
+
businessLogo: string | null;
|
|
956
|
+
businessName: string;
|
|
957
|
+
}
|
|
958
|
+
/**
|
|
959
|
+
* An open checkout session, as returned by `checkoutSessions.retrieve()` (`openapi.yaml`
|
|
960
|
+
* `CheckoutSession`). Only an open session can be read: once paid or expired, retrieving it throws
|
|
961
|
+
* `NotFoundError`.
|
|
962
|
+
*/
|
|
963
|
+
interface CheckoutSession {
|
|
964
|
+
publicId: string;
|
|
965
|
+
lineItems: CheckoutLineItem[];
|
|
966
|
+
/** The `cus_…` the session was opened with, or `null` if the buyer enters their own details. */
|
|
967
|
+
customerId: string | null;
|
|
968
|
+
sellerDetails: CheckoutSeller;
|
|
969
|
+
returnUrl: string;
|
|
970
|
+
/** Kept as sent (may carry a `+05:45` offset). */
|
|
971
|
+
expiresAt: string;
|
|
972
|
+
completedAt: string | null;
|
|
973
|
+
isExpired: boolean;
|
|
974
|
+
/**
|
|
975
|
+
* What the session was opened for: `"subscription"` or `"billing"` today, and any value the API
|
|
976
|
+
* adds later. `null` if the API doesn't send it.
|
|
977
|
+
*/
|
|
978
|
+
sessionType: CheckoutSessionType | null;
|
|
730
979
|
}
|
|
731
980
|
|
|
732
981
|
/**
|
|
733
|
-
* The confirmed webhook event payload shapes
|
|
734
|
-
*
|
|
735
|
-
*
|
|
982
|
+
* The confirmed webhook event payload shapes, re-checked on 2026-11-19 against delivery samples
|
|
983
|
+
* captured and shared by the backend team for every event (checkout, renewal, status change and
|
|
984
|
+
* all four `api_key.*` events).
|
|
736
985
|
*
|
|
737
986
|
* Deliberately **snake_case**, unlike every other model in this SDK — `webhooks.verify()`
|
|
738
987
|
* (Ticket 5) only checks the signature and returns a `boolean`; it never parses the body itself
|
|
@@ -744,32 +993,56 @@ interface MessageResponse {
|
|
|
744
993
|
* @packageDocumentation
|
|
745
994
|
*/
|
|
746
995
|
/**
|
|
747
|
-
*
|
|
748
|
-
*
|
|
749
|
-
*
|
|
750
|
-
* not because every webhook event SUQO will ever send is guaranteed to carry one. A future event
|
|
751
|
-
* about a different resource (e.g. a customer- or payout-level event) would need its own base, not
|
|
752
|
-
* be forced through this one. SDK Naming Map v1.1 has no coverage of this at all — same gap as the
|
|
753
|
-
* event fields themselves.
|
|
996
|
+
* One line item on a `checkout.*` event. A catalogue item has a `pbp_id` and `image_urls`; a
|
|
997
|
+
* partner-priced (inline) item has `pbp_id: null` and `plan_name`. Internal alias — the Naming Map
|
|
998
|
+
* registers no public name for it.
|
|
754
999
|
*/
|
|
755
|
-
interface
|
|
756
|
-
|
|
1000
|
+
interface CheckoutEventLineItem {
|
|
1001
|
+
name: string;
|
|
1002
|
+
/** Decimal string. Never coerced to a number — SDK-SPEC.md §9. */
|
|
1003
|
+
amount: string;
|
|
1004
|
+
/** The billing period charged; `null` for a partner-priced item. */
|
|
1005
|
+
pbp_id: string | null;
|
|
1006
|
+
currency: string;
|
|
1007
|
+
vat_type: VatType | null;
|
|
1008
|
+
/** Decimal string, or `null` when no VAT applies. */
|
|
1009
|
+
vat_percentage: string | null;
|
|
1010
|
+
/** Decimal string, or `null` when there is no discount. */
|
|
1011
|
+
discount_amount: string | null;
|
|
1012
|
+
interval_type: IntervalType;
|
|
1013
|
+
interval_count: number;
|
|
1014
|
+
/** Catalogue items only. */
|
|
1015
|
+
image_urls?: string[];
|
|
1016
|
+
/** Partner-priced items only. */
|
|
1017
|
+
plan_name?: string | null;
|
|
1018
|
+
/** Only on a payment opened by `subscriptions.renew()`: the subscription being renewed. */
|
|
1019
|
+
subscription_id?: string;
|
|
1020
|
+
}
|
|
1021
|
+
/**
|
|
1022
|
+
* Fields shared by both checkout events. **Changed in 2.0.0:** one delivery per checkout
|
|
1023
|
+
* session, keyed by `session_id`, carrying `line_items` — not one per subscription keyed by a
|
|
1024
|
+
* top-level `subscription_id`. Payments taken through the legacy `subscriptions.create()` report
|
|
1025
|
+
* through this same payload.
|
|
1026
|
+
*/
|
|
1027
|
+
interface CheckoutWebhookEventBase {
|
|
1028
|
+
/** The `cks_…` returned as `publicId` when the session was opened — match deliveries back on this. */
|
|
1029
|
+
session_id: string;
|
|
1030
|
+
/** The session total. Decimal string. Never coerced to a number — SDK-SPEC.md §9. */
|
|
1031
|
+
amount: string;
|
|
1032
|
+
/** What the session charged, one entry per item. */
|
|
1033
|
+
line_items: CheckoutEventLineItem[];
|
|
757
1034
|
}
|
|
758
1035
|
/** A successful checkout. `status` is always `"succeeded"` on this event — never anything else. */
|
|
759
|
-
interface CheckoutSucceededEvent extends
|
|
1036
|
+
interface CheckoutSucceededEvent extends CheckoutWebhookEventBase {
|
|
760
1037
|
event: "checkout.succeeded";
|
|
761
|
-
/** Decimal string. Never coerced to a number — SDK-SPEC.md §9. */
|
|
762
|
-
amount: string;
|
|
763
1038
|
status: "succeeded";
|
|
764
1039
|
}
|
|
765
1040
|
/**
|
|
766
|
-
* A failed checkout. `status` is always `"failed"
|
|
767
|
-
* failure reason
|
|
1041
|
+
* A failed checkout — final, after SUQO's own retries. `status` is always `"failed"`; the specific
|
|
1042
|
+
* failure reason is deliberately not in the payload.
|
|
768
1043
|
*/
|
|
769
|
-
interface CheckoutFailedEvent extends
|
|
1044
|
+
interface CheckoutFailedEvent extends CheckoutWebhookEventBase {
|
|
770
1045
|
event: "checkout.failed";
|
|
771
|
-
/** Decimal string. Never coerced to a number — SDK-SPEC.md §9. */
|
|
772
|
-
amount: string;
|
|
773
1046
|
status: "failed";
|
|
774
1047
|
}
|
|
775
1048
|
/**
|
|
@@ -778,8 +1051,9 @@ interface CheckoutFailedEvent extends SubscriptionWebhookEventBase {
|
|
|
778
1051
|
* §9's prose still says `subscription.status.change`; that's the doc that's stale, not this type
|
|
779
1052
|
* (docs/implementation-plan.md Ticket 0 item 2).
|
|
780
1053
|
*/
|
|
781
|
-
interface SubscriptionStatusChangedEvent
|
|
1054
|
+
interface SubscriptionStatusChangedEvent {
|
|
782
1055
|
event: "subscription.status_changed";
|
|
1056
|
+
subscription_id: string;
|
|
783
1057
|
previous_status: SubscriptionStatus;
|
|
784
1058
|
current_status: SubscriptionStatus;
|
|
785
1059
|
/** ISO 8601 timestamp. */
|
|
@@ -792,8 +1066,11 @@ interface ApiKeyWebhookEventBase {
|
|
|
792
1066
|
name: string;
|
|
793
1067
|
/** Never the real key — always pre-masked by the backend (e.g. `"su_key_ca9...bf9e"`). */
|
|
794
1068
|
masked_key: string;
|
|
795
|
-
/**
|
|
796
|
-
|
|
1069
|
+
/**
|
|
1070
|
+
* `YYYY-MM-DD`, date-only — no time component, unlike `created_at`/`deleted_at`. `null` for a key
|
|
1071
|
+
* created without an expiry.
|
|
1072
|
+
*/
|
|
1073
|
+
expires_at: string | null;
|
|
797
1074
|
/** ISO 8601 timestamp. */
|
|
798
1075
|
created_at: string;
|
|
799
1076
|
}
|
|
@@ -828,6 +1105,77 @@ type WebhookEvent = CheckoutSucceededEvent | CheckoutFailedEvent | SubscriptionS
|
|
|
828
1105
|
*/
|
|
829
1106
|
type WebhookEventType = WebhookEvent["event"];
|
|
830
1107
|
|
|
1108
|
+
/**
|
|
1109
|
+
* The webhook-management model types (`specs/openapi.yaml` `Webhook` / `CreateWebhookRequest` /
|
|
1110
|
+
* `ReplaceWebhookRequest` / `UpdateWebhookRequest` / `WebhookSecret` — SDK-SPEC.md §5, §9).
|
|
1111
|
+
* These describe *registrations* — which endpoint receives which event. The deliveries themselves
|
|
1112
|
+
* are typed in `./WebhookEvent.js`.
|
|
1113
|
+
*
|
|
1114
|
+
* @packageDocumentation
|
|
1115
|
+
*/
|
|
1116
|
+
/**
|
|
1117
|
+
* A known {@link WebhookEventType} with autocomplete, or any other event name — so a {@link
|
|
1118
|
+
* Webhook.event} read back can be written back as-is, and an event the API adds after this SDK
|
|
1119
|
+
* release can still be registered.
|
|
1120
|
+
*/
|
|
1121
|
+
type WebhookEventName = WebhookEventType | (string & {});
|
|
1122
|
+
/** A webhook registration (`openapi.yaml` `Webhook`). One per event per account. */
|
|
1123
|
+
interface Webhook {
|
|
1124
|
+
/** `whk_…` */
|
|
1125
|
+
id: string;
|
|
1126
|
+
/** The event this endpoint receives — a known {@link WebhookEventType}, or a newer one the SDK doesn't know yet. */
|
|
1127
|
+
event: WebhookEventName;
|
|
1128
|
+
endpointUrl: string;
|
|
1129
|
+
/** `false` while deliveries are paused. */
|
|
1130
|
+
isActive: boolean;
|
|
1131
|
+
createdAt: string;
|
|
1132
|
+
}
|
|
1133
|
+
/** What `webhooks.create(params)` accepts (`openapi.yaml` `CreateWebhookRequest`, renamed). */
|
|
1134
|
+
interface CreateWebhookParams {
|
|
1135
|
+
/** One webhook per event per account — a second for the same event is a `ValidationError`. */
|
|
1136
|
+
event: WebhookEventName;
|
|
1137
|
+
/** Must be `https` and resolve only to public addresses. */
|
|
1138
|
+
endpointUrl: string;
|
|
1139
|
+
isActive?: boolean;
|
|
1140
|
+
}
|
|
1141
|
+
/**
|
|
1142
|
+
* What `webhooks.replace(id, params)` accepts (`openapi.yaml` `ReplaceWebhookRequest`, renamed) —
|
|
1143
|
+
* a full overwrite (`PUT`): `event` and `endpointUrl` are both required. To change one field on
|
|
1144
|
+
* its own, use `webhooks.update()`.
|
|
1145
|
+
*/
|
|
1146
|
+
interface ReplaceWebhookParams {
|
|
1147
|
+
event: WebhookEventName;
|
|
1148
|
+
endpointUrl: string;
|
|
1149
|
+
isActive?: boolean;
|
|
1150
|
+
}
|
|
1151
|
+
/**
|
|
1152
|
+
* What `webhooks.update(id, params)` accepts (`openapi.yaml` `UpdateWebhookRequest`, renamed) — a
|
|
1153
|
+
* partial update (`PATCH`): send only what changes, e.g. `{ isActive: false }` to pause deliveries.
|
|
1154
|
+
*/
|
|
1155
|
+
interface UpdateWebhookParams {
|
|
1156
|
+
event?: WebhookEventName;
|
|
1157
|
+
endpointUrl?: string;
|
|
1158
|
+
isActive?: boolean;
|
|
1159
|
+
}
|
|
1160
|
+
/** What `webhooks.retrieveSecret()` returns (`openapi.yaml` `WebhookSecret`). */
|
|
1161
|
+
interface WebhookSecret {
|
|
1162
|
+
/** `whsec_…` — pass it as `secret` to `webhooks.verify()`. Treat it like a password: never log it. */
|
|
1163
|
+
signingSecret: string;
|
|
1164
|
+
}
|
|
1165
|
+
|
|
1166
|
+
/**
|
|
1167
|
+
* What `subscriptions.cancel()`, `subscriptions.updateBillingCycle()`, and
|
|
1168
|
+
* `subscriptions.resume()` all return (`specs/openapi.yaml` `Message`, renamed). Named
|
|
1169
|
+
* `MessageResponse`, not `Message` — SDK Naming Map v1.1 §12: `Message` collides with the
|
|
1170
|
+
* `message` property every {@link import("../errors/SuqoError.js").SuqoError} subclass already
|
|
1171
|
+
* carries.
|
|
1172
|
+
*
|
|
1173
|
+
* @packageDocumentation
|
|
1174
|
+
*/
|
|
1175
|
+
interface MessageResponse {
|
|
1176
|
+
message: string;
|
|
1177
|
+
}
|
|
1178
|
+
|
|
831
1179
|
/**
|
|
832
1180
|
* `client.products` (SDK-SPEC.md §5, §6; `openapi.yaml` `listProducts`). The only resource that
|
|
833
1181
|
* works before KYC verification — no `KycRequiredError` case to handle here.
|
|
@@ -847,10 +1195,11 @@ declare class ProductsResource {
|
|
|
847
1195
|
|
|
848
1196
|
/**
|
|
849
1197
|
* `client.subscriptions` (SDK-SPEC.md §5, §6, §7; `openapi.yaml` `listSubscriptions`/
|
|
850
|
-
* `createSubscription`/`cancelSubscription`/`updateBillingCycle
|
|
1198
|
+
* `retrieveSubscription`/`createSubscription`/`cancelSubscription`/`updateBillingCycle`/
|
|
1199
|
+
* `resumeSubscription`/`renewSubscription`).
|
|
851
1200
|
*
|
|
852
|
-
*
|
|
853
|
-
*
|
|
1201
|
+
* One-time purchases (a billing period whose `intervalType` is `one_time`) appear in `list()` but
|
|
1202
|
+
* can't be cancelled, resumed, rescheduled or renewed — those calls throw `ValidationError`.
|
|
854
1203
|
*/
|
|
855
1204
|
declare class SubscriptionsResource {
|
|
856
1205
|
#private;
|
|
@@ -866,13 +1215,21 @@ declare class SubscriptionsResource {
|
|
|
866
1215
|
*/
|
|
867
1216
|
autoPaging(params?: PageParams): AsyncIterableIterator<Subscription>;
|
|
868
1217
|
/**
|
|
1218
|
+
* Retrieves one of your own subscriptions by id. Built from Swagger's schema; not yet checked
|
|
1219
|
+
* against a captured response.
|
|
1220
|
+
*/
|
|
1221
|
+
retrieve(id: string): Promise<Subscription>;
|
|
1222
|
+
/**
|
|
1223
|
+
* **Legacy** — prefer `checkoutSessions.create()`, which takes up to ten items in one payment
|
|
1224
|
+
* and doesn't need a full customer object. Still supported; existing integrations keep working.
|
|
1225
|
+
*
|
|
869
1226
|
* Creates a subscription in `pending_checkout` state and returns a checkout URL for the buyer
|
|
870
1227
|
* to pay (SDK-SPEC.md §5). Redirect the buyer to `checkoutUrl`; the return is **not** proof of
|
|
871
1228
|
* payment — learn the real outcome via the `checkout.succeeded`/`checkout.failed` webhooks.
|
|
872
1229
|
*
|
|
873
|
-
*
|
|
874
|
-
*
|
|
875
|
-
*
|
|
1230
|
+
* `customer.email` identifies the buyer. A buyer may hold only one live recurring subscription
|
|
1231
|
+
* per product: a second one on any billing period of the same product throws `ValidationError`.
|
|
1232
|
+
* To restart an inactive subscription, use `renew()` rather than creating a new one.
|
|
876
1233
|
*
|
|
877
1234
|
* Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
|
|
878
1235
|
*/
|
|
@@ -880,7 +1237,9 @@ declare class SubscriptionsResource {
|
|
|
880
1237
|
/**
|
|
881
1238
|
* Schedules cancellation for the end of the current billing period — **not** immediate
|
|
882
1239
|
* (confirmed with backend 2026-08-17; immediate cancellation is a future capability). Status
|
|
883
|
-
* moves to `pending_cancellation`; the subscription stays active until the period ends.
|
|
1240
|
+
* moves to `pending_cancellation`; the subscription stays active until the period ends. Calling
|
|
1241
|
+
* it on a subscription already cancelled or pending cancellation returns it unchanged, so a
|
|
1242
|
+
* retry by the caller is safe.
|
|
884
1243
|
*
|
|
885
1244
|
* Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
|
|
886
1245
|
*/
|
|
@@ -893,18 +1252,29 @@ declare class SubscriptionsResource {
|
|
|
893
1252
|
*/
|
|
894
1253
|
updateBillingCycle(params: UpdateBillingCycleParams): Promise<MessageResponse>;
|
|
895
1254
|
/**
|
|
896
|
-
*
|
|
897
|
-
*
|
|
898
|
-
*
|
|
1255
|
+
* Undoes a scheduled cancellation and returns the subscription to `active`. An already-active
|
|
1256
|
+
* subscription is returned unchanged. Once a subscription is `cancelled` there is nothing to
|
|
1257
|
+
* resume — use `renew()`.
|
|
899
1258
|
*
|
|
900
1259
|
* Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
|
|
901
1260
|
*/
|
|
902
1261
|
resume(id: string): Promise<MessageResponse>;
|
|
1262
|
+
/**
|
|
1263
|
+
* Opens a checkout session for the next payment on one of your own subscriptions, reusing its
|
|
1264
|
+
* customer and billing period (or partner-priced item) rather than resubmitting them — how an
|
|
1265
|
+
* inactive subscription is restarted. Send the buyer to the returned `checkoutUrl`, and learn
|
|
1266
|
+
* the outcome from the `checkout.*` webhooks, matched on `publicId`.
|
|
1267
|
+
*
|
|
1268
|
+
* A cancelled or archived subscription, or a paid one-time purchase, can't be renewed: that
|
|
1269
|
+
* throws `ValidationError`. Not auto-retryable — writes never retry until idempotency ships
|
|
1270
|
+
* (SDK-SPEC.md §8, §12).
|
|
1271
|
+
*/
|
|
1272
|
+
renew(subscriptionId: string): Promise<CheckoutSessionResponse>;
|
|
903
1273
|
}
|
|
904
1274
|
|
|
905
1275
|
/**
|
|
906
|
-
* `client.customers` (SDK-SPEC.md §5, §6; `openapi.yaml` `listCustomers`/`retrieveCustomer
|
|
907
|
-
*
|
|
1276
|
+
* `client.customers` (SDK-SPEC.md §5, §6; `openapi.yaml` `listCustomers`/`retrieveCustomer`/
|
|
1277
|
+
* `createCustomer`/`updateCustomer`). No delete exists on this resource.
|
|
908
1278
|
*/
|
|
909
1279
|
declare class CustomersResource {
|
|
910
1280
|
#private;
|
|
@@ -918,20 +1288,59 @@ declare class CustomersResource {
|
|
|
918
1288
|
*/
|
|
919
1289
|
autoPaging(params?: PageParams): AsyncIterableIterator<Customer>;
|
|
920
1290
|
/**
|
|
921
|
-
* Retrieves a single customer by id
|
|
922
|
-
*
|
|
1291
|
+
* Retrieves a single customer by id — an opaque prefixed string (e.g. `"cus_1ce18d624"`), like
|
|
1292
|
+
* `pbp_...` on billing periods, not an integer and not a UUID (Bug #42 corrected the previously
|
|
1293
|
+
* wrong `number` type/doc claim here).
|
|
1294
|
+
*/
|
|
1295
|
+
retrieve(id: string): Promise<Customer>;
|
|
1296
|
+
/**
|
|
1297
|
+
* Records a customer on the seller's account without opening a subscription. `email` identifies
|
|
1298
|
+
* the buyer and is required; `phone` is optional. The name and address are the seller's own copy
|
|
1299
|
+
* and aren't shared with other sellers. Pass the returned `id` to `checkoutSessions.create()` as
|
|
1300
|
+
* `customerId` to send the buyer straight to payment.
|
|
1301
|
+
*
|
|
1302
|
+
* An email or phone the seller already holds updates that existing customer instead of creating
|
|
1303
|
+
* a second one (the API answers `200` rather than `201`; both resolve to the `Customer` here).
|
|
1304
|
+
* That makes this call safe for the caller to retry — but, like every write, the SDK never
|
|
1305
|
+
* retries it automatically (SDK-SPEC.md §8, §12).
|
|
1306
|
+
*/
|
|
1307
|
+
create(params: CreateCustomerParams): Promise<Customer>;
|
|
1308
|
+
/**
|
|
1309
|
+
* Updates the seller's copy of a customer's name, email or address. Send only the fields you're
|
|
1310
|
+
* changing; `""` clears a field. The phone can't be changed.
|
|
1311
|
+
*
|
|
1312
|
+
* Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
|
|
923
1313
|
*/
|
|
924
|
-
|
|
1314
|
+
update(id: string, params: UpdateCustomerParams): Promise<Customer>;
|
|
925
1315
|
}
|
|
926
1316
|
|
|
927
1317
|
/**
|
|
928
|
-
* `client.
|
|
929
|
-
*
|
|
930
|
-
*
|
|
931
|
-
* event body itself (see `models/WebhookEvent.ts` for why the event types stay snake_case).
|
|
932
|
-
*
|
|
933
|
-
* @packageDocumentation
|
|
1318
|
+
* `client.checkoutSessions` (SDK-SPEC.md §5; `openapi.yaml` `createCheckoutSession`/
|
|
1319
|
+
* `retrieveCheckoutSession`). The recommended way to collect payment: up to ten items in one
|
|
1320
|
+
* checkout, replacing the legacy `subscriptions.create()`.
|
|
934
1321
|
*/
|
|
1322
|
+
declare class CheckoutSessionsResource {
|
|
1323
|
+
#private;
|
|
1324
|
+
constructor(http: HttpClient);
|
|
1325
|
+
/**
|
|
1326
|
+
* Opens a checkout session for one to ten items and returns a URL for the buyer to pay. Prices
|
|
1327
|
+
* are snapshotted now, so a plan edited later can't change what the buyer was shown. Redirect
|
|
1328
|
+
* the buyer to `checkoutUrl`; the return to `returnUrl` is **not** proof of payment — learn the
|
|
1329
|
+
* outcome from `checkout.succeeded`/`checkout.failed`, matched on `publicId` (`session_id`).
|
|
1330
|
+
*
|
|
1331
|
+
* The API's one rate-limited endpoint: 20 sessions a minute per account. Past that it throws
|
|
1332
|
+
* `RateLimitError` with `retryAfter` set. Never retried automatically — writes don't retry until
|
|
1333
|
+
* idempotency ships (SDK-SPEC.md §8, §12) — so open a session when the buyer commits to paying,
|
|
1334
|
+
* not on page load.
|
|
1335
|
+
*/
|
|
1336
|
+
create(params: CreateCheckoutSessionParams): Promise<CheckoutSessionResponse>;
|
|
1337
|
+
/**
|
|
1338
|
+
* Reads one of your own open sessions: its line items, customer, seller and expiry. Once paid,
|
|
1339
|
+
* expired, unknown or someone else's, it throws `NotFoundError`.
|
|
1340
|
+
*/
|
|
1341
|
+
retrieve(id: string): Promise<CheckoutSession>;
|
|
1342
|
+
}
|
|
1343
|
+
|
|
935
1344
|
/** Options accepted by {@link WebhooksResource.verify}. */
|
|
936
1345
|
interface VerifyWebhookOptions {
|
|
937
1346
|
/**
|
|
@@ -955,6 +1364,44 @@ interface VerifyWebhookOptions {
|
|
|
955
1364
|
toleranceSec?: number;
|
|
956
1365
|
}
|
|
957
1366
|
declare class WebhooksResource {
|
|
1367
|
+
#private;
|
|
1368
|
+
constructor(http: HttpClient);
|
|
1369
|
+
/** Every webhook registered by your account. Not paginated — the API returns them all. */
|
|
1370
|
+
list(): Promise<Webhook[]>;
|
|
1371
|
+
/**
|
|
1372
|
+
* Subscribes an `https` endpoint to one event. An account holds at most one webhook per event,
|
|
1373
|
+
* and the endpoint must resolve only to public addresses — either failing throws
|
|
1374
|
+
* `ValidationError`. Not auto-retryable (SDK-SPEC.md §8, §12).
|
|
1375
|
+
*/
|
|
1376
|
+
create(params: CreateWebhookParams): Promise<Webhook>;
|
|
1377
|
+
/** Retrieves one of your own webhooks by id (`whk_…`). */
|
|
1378
|
+
retrieve(id: string): Promise<Webhook>;
|
|
1379
|
+
/**
|
|
1380
|
+
* Overwrites a webhook's event, endpoint and active flag (`PUT`). `event` and `endpointUrl` are
|
|
1381
|
+
* both required; to change one field on its own, use {@link WebhooksResource.update}. Not
|
|
1382
|
+
* auto-retryable (SDK-SPEC.md §8, §12).
|
|
1383
|
+
*/
|
|
1384
|
+
replace(id: string, params: ReplaceWebhookParams): Promise<Webhook>;
|
|
1385
|
+
/**
|
|
1386
|
+
* Changes only the fields you send (`PATCH`) — e.g. `{ isActive: false }` pauses deliveries
|
|
1387
|
+
* without deleting the webhook. Not auto-retryable (SDK-SPEC.md §8, §12).
|
|
1388
|
+
*/
|
|
1389
|
+
update(id: string, params: UpdateWebhookParams): Promise<Webhook>;
|
|
1390
|
+
/** Removes a webhook. Past delivery records are kept for debugging. Not auto-retryable (SDK-SPEC.md §8, §12). */
|
|
1391
|
+
delete(id: string): Promise<void>;
|
|
1392
|
+
/**
|
|
1393
|
+
* Returns the account's signing secret — the `secret` to pass to {@link WebhooksResource.verify}.
|
|
1394
|
+
* The API creates it on the first call; it can't be rotated through the API. Treat it like a
|
|
1395
|
+
* password: never log it.
|
|
1396
|
+
*/
|
|
1397
|
+
retrieveSecret(): Promise<WebhookSecret>;
|
|
1398
|
+
/**
|
|
1399
|
+
* Queues a signed test delivery to the webhook's endpoint so you can check your receiver. It
|
|
1400
|
+
* resolves once the job is queued; the delivery itself arrives asynchronously. Note a test
|
|
1401
|
+
* delivery's body differs from a real event's (fields under `data`) — use it to check
|
|
1402
|
+
* `verify()`, not your payload parsing. Not auto-retryable (SDK-SPEC.md §8, §12).
|
|
1403
|
+
*/
|
|
1404
|
+
testDelivery(id: string): Promise<void>;
|
|
958
1405
|
/**
|
|
959
1406
|
* Verifies an inbound webhook delivery's signature. Returns `false` for any failure mode —
|
|
960
1407
|
* malformed signature, expired timestamp, or a genuine mismatch — never throws, so a caller
|
|
@@ -1005,10 +1452,9 @@ interface SuqoClientOptions {
|
|
|
1005
1452
|
* else to configure in the common case (SDK-SPEC.md §2). Construction throws `SuqoConfigError`
|
|
1006
1453
|
* immediately on a malformed key, or on a `baseUrl` override that disagrees with the key.
|
|
1007
1454
|
*
|
|
1008
|
-
*
|
|
1009
|
-
* `
|
|
1010
|
-
*
|
|
1011
|
-
* call and needs no key at all (SDK-SPEC.md §9), so it's constructed independently.
|
|
1455
|
+
* Every resource shares this one instance's `HttpClient` — same `baseUrl`/`apiKey`/`timeout`/
|
|
1456
|
+
* `maxRetries` for every call, regardless of which resource makes it. `webhooks.verify()` is the
|
|
1457
|
+
* one method that makes no network call (SDK-SPEC.md §9).
|
|
1012
1458
|
*/
|
|
1013
1459
|
declare class SuqoClient {
|
|
1014
1460
|
#private;
|
|
@@ -1016,9 +1462,14 @@ declare class SuqoClient {
|
|
|
1016
1462
|
readonly products: ProductsResource;
|
|
1017
1463
|
/** Create, list, and manage subscriptions (SDK-SPEC.md §5, §6, §7). */
|
|
1018
1464
|
readonly subscriptions: SubscriptionsResource;
|
|
1019
|
-
/** List and
|
|
1465
|
+
/** List, retrieve, create and update the seller's customers (SDK-SPEC.md §5, §6). */
|
|
1020
1466
|
readonly customers: CustomersResource;
|
|
1021
|
-
/**
|
|
1467
|
+
/** Open and read checkout sessions — the recommended way to collect payment (SDK-SPEC.md §5). */
|
|
1468
|
+
readonly checkoutSessions: CheckoutSessionsResource;
|
|
1469
|
+
/**
|
|
1470
|
+
* Manage webhook registrations, and verify inbound deliveries (SDK-SPEC.md §5, §9). `verify()`
|
|
1471
|
+
* makes no network call; the management methods do.
|
|
1472
|
+
*/
|
|
1022
1473
|
readonly webhooks: WebhooksResource;
|
|
1023
1474
|
constructor(options: SuqoClientOptions);
|
|
1024
1475
|
/** `"sandbox" | "live"` — inferred from the key prefix, never selected explicitly (SDK-SPEC.md §2). */
|
|
@@ -1040,6 +1491,6 @@ declare class SuqoClient {
|
|
|
1040
1491
|
* @packageDocumentation
|
|
1041
1492
|
*/
|
|
1042
1493
|
/** SDK version, stamped into request headers (keep in sync with package.json). */
|
|
1043
|
-
declare const VERSION = "
|
|
1494
|
+
declare const VERSION = "2.0.0";
|
|
1044
1495
|
|
|
1045
|
-
export { type ApiKeyCreatedEvent, type ApiKeyDeletedEvent, type ApiKeyExpiredEvent, type ApiKeyExpiringSoonEvent, AuthenticationError, type BillingPeriod, type CheckoutFailedEvent, type CheckoutSucceededEvent, 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 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, VERSION, ValidationError, type ValidationErrorOptions, type VerifyWebhookOptions, type WebhookEvent, type WebhookEventType, bridgeAutoPaging, deserializePage, listAll, mapHttpError, toPageQuery };
|
|
1496
|
+
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 };
|