@suqo/sdk 1.1.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/dist/index.d.cts CHANGED
@@ -86,6 +86,16 @@ 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
+ * 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
+ }
89
99
  /**
90
100
  * 400 — request validation failed (SDK-SPEC.md §7). The API uses two different 400 body shapes;
91
101
  * {@link mapHttpError} normalizes both into this one class so consumers rely on `instanceof`,
@@ -112,12 +122,15 @@ interface RateLimitErrorOptions extends SuqoErrorOptions {
112
122
  retryAfter?: number;
113
123
  }
114
124
  /**
115
- * 429 — rate limited (SDK-SPEC.md §7). **Reserved**: the API does not enforce rate limiting yet
116
- * and never emits 429 today; this class exists so the SDK is forward-ready the moment it does
117
- * (SDK-SPEC.md §10).
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.
118
128
  */
119
129
  declare class RateLimitError extends SuqoError {
120
- /** Suggested backoff derived from a `Retry-After` header, in milliseconds, if present. See {@link RateLimitErrorOptions.retryAfter}. */
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
+ */
121
134
  readonly retryAfter?: number;
122
135
  constructor(message: string, options?: RateLimitErrorOptions);
123
136
  }
@@ -303,12 +316,29 @@ interface HttpPatchRequestOptions<TBody = unknown> extends HttpRequestOptionsBas
303
316
  /** JSON-serializable request body — only the fields being changed. */
304
317
  body?: TBody;
305
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
+ }
306
336
  /**
307
337
  * Options accepted by {@link HttpClient.request}. `HttpClient` itself is internal (not exported
308
338
  * from `src/index.ts`); the SDK's actual typed, consumer-facing contract lives one layer up, in
309
339
  * each resource method's own public signature.
310
340
  */
311
- type HttpRequestOptions<TBody = unknown> = HttpGetRequestOptions | HttpPostRequestOptions<TBody> | HttpPatchRequestOptions<TBody>;
341
+ type HttpRequestOptions<TBody = unknown> = HttpGetRequestOptions | HttpPostRequestOptions<TBody> | HttpPatchRequestOptions<TBody> | HttpPutRequestOptions<TBody> | HttpDeleteRequestOptions;
312
342
  /** Options accepted by {@link HttpClient}'s constructor. */
313
343
  interface HttpClientOptions {
314
344
  /**
@@ -466,6 +496,27 @@ declare function listAll<T>(firstPage: Page<T>, fetchNext: (nextUrl: string) =>
466
496
  */
467
497
  declare function bridgeAutoPaging<T>(fetchFirstPage: () => Promise<Page<T>>, fetchNext: (nextUrl: string) => Promise<Page<T>>, maxPages?: number): AsyncIterableIterator<T>;
468
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
+
469
520
  /**
470
521
  * The `products` resource's model types (`specs/openapi.yaml` `Product`/`Plan`/`BillingPeriod` —
471
522
  * SDK-SPEC.md §5). Field names are camelCase per R3; nothing here is renamed from the wire (R5) —
@@ -473,12 +524,14 @@ declare function bridgeAutoPaging<T>(fetchFirstPage: () => Promise<Page<T>>, fet
473
524
  *
474
525
  * @packageDocumentation
475
526
  */
527
+
476
528
  /** VAT configuration for a {@link Product}, if any. */
477
529
  interface ProductVat {
478
530
  isVatActive: boolean;
479
- vatType: string;
480
- /** Decimal string (e.g. `"13.00"`). Never coerced to a number — SDK-SPEC.md §5. */
481
- vatPercentage: string;
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;
482
535
  }
483
536
  /** One image on a {@link Product} (`openapi.yaml` `ProductImage`). */
484
537
  interface ProductImage {
@@ -491,11 +544,11 @@ interface ProductImage {
491
544
  interface Product {
492
545
  productId: string;
493
546
  name: string;
494
- description: string;
495
- type: string;
547
+ description: string | null;
548
+ type: ProductType;
496
549
  isActive: boolean;
497
- termsAndConditions: string;
498
- featuresAndBenefits: string;
550
+ termsAndConditions: string | null;
551
+ featuresAndBenefits: string | null;
499
552
  vat: ProductVat | null;
500
553
  /**
501
554
  * Ordered images; blank images already excluded server-side. Each is an object, not a bare URL
@@ -512,7 +565,7 @@ interface Product {
512
565
  interface Plan {
513
566
  planId: string;
514
567
  planName: string;
515
- description: string;
568
+ description: string | null;
516
569
  billingPeriods: BillingPeriod[];
517
570
  }
518
571
  /**
@@ -522,7 +575,11 @@ interface Plan {
522
575
  interface BillingPeriod {
523
576
  /** Public id — pass this to `subscriptions.create({ pbpId, ... })`. */
524
577
  pbpId: string;
525
- intervalType: string;
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;
526
583
  intervalCount: number;
527
584
  label: string;
528
585
  /** Decimal string. Never coerced to a number — SDK-SPEC.md §5. */
@@ -531,8 +588,21 @@ interface BillingPeriod {
531
588
  isCurrent: boolean;
532
589
  isLimited: boolean;
533
590
  isArchived: boolean;
534
- /** Wire schema is an empty item type (`items: {}`) — shape not yet specified by the API. */
535
- offers: unknown[];
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;
536
606
  }
537
607
 
538
608
  /**
@@ -663,17 +733,21 @@ declare const SubscriptionStatus: {
663
733
  * runtime.
664
734
  */
665
735
  type SubscriptionStatus = (typeof SubscriptionStatus)[keyof typeof SubscriptionStatus] | (string & {});
666
- /** The product summary embedded on a {@link Subscription} (`openapi.yaml` `SubscriptionProduct`) — a summary, not the full {@link import("./Product.js").Product} record. */
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
+ */
667
741
  interface SubscriptionProduct {
668
- productId: string;
669
- name: string;
670
- planName: string;
742
+ productId: string | null;
743
+ name: string | null;
744
+ planName: string | null;
671
745
  /** Pass this to `subscriptions.create({ pbpId, ... })`. */
672
- pbpId: string;
673
- label: string;
746
+ pbpId: string | null;
747
+ label: string | null;
674
748
  /** Decimal string. Never coerced to a number — SDK-SPEC.md §5. */
675
- price: string;
676
- currency: string;
749
+ price: string | null;
750
+ currency: string | null;
677
751
  }
678
752
  /** A seller's subscription (`openapi.yaml` `Subscription`). */
679
753
  interface Subscription {
@@ -752,15 +826,15 @@ interface UpdateBillingCycleParams {
752
826
  */
753
827
  /** What `customers.create(params)` accepts (`openapi.yaml` `CreateCustomerRequest`, renamed). */
754
828
  interface CreateCustomerParams {
829
+ /** Identifies the buyer. Required. Reads back as `buyerEmail`. */
830
+ email: string;
755
831
  /**
756
- * Identifies the buyer and can't be changed later. A Nepali mobile number: 10 digits starting
757
- * with 96, 97 or 98 — a `+977` country code, a leading 0, spaces and dashes are accepted and
758
- * stripped server-side. Reads back as `buyerPhone`.
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`.
759
835
  */
760
- phone: string;
836
+ phone?: string;
761
837
  fullName?: string;
762
- /** Reads back as `buyerEmail`. */
763
- email?: string;
764
838
  address?: string;
765
839
  }
766
840
  /**
@@ -776,22 +850,138 @@ interface UpdateCustomerParams {
776
850
  }
777
851
 
778
852
  /**
779
- * What `subscriptions.cancel()`, `subscriptions.updateBillingCycle()`, and
780
- * `subscriptions.resume()` all return (`specs/openapi.yaml` `Message`, renamed). Named
781
- * `MessageResponse`, not `Message` — SDK Naming Map v1.1 §12: `Message` collides with the
782
- * `message` property every {@link import("../errors/SuqoError.js").SuqoError} subclass already
783
- * carries.
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}.
784
858
  *
785
859
  * @packageDocumentation
786
860
  */
787
- interface MessageResponse {
788
- message: string;
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;
789
979
  }
790
980
 
791
981
  /**
792
- * The confirmed webhook event payload shapes: the original three (Ticket 0 item 2) plus four
793
- * `api_key.*` events added 2026-09-03, each confirmed against a real delivery or a backend-
794
- * confirmed sample — not the event catalog's names alone.
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).
795
985
  *
796
986
  * Deliberately **snake_case**, unlike every other model in this SDK — `webhooks.verify()`
797
987
  * (Ticket 5) only checks the signature and returns a `boolean`; it never parses the body itself
@@ -803,32 +993,56 @@ interface MessageResponse {
803
993
  * @packageDocumentation
804
994
  */
805
995
  /**
806
- * Fields shared by every *subscription-related* webhook event (2026-08-25).
807
- * Deliberately named for **subscription** events specifically, not a generic `BaseWebhookEvent` —
808
- * `subscription_id` is common to these three because all three happen to be about a subscription,
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.
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.
813
999
  */
814
- interface SubscriptionWebhookEventBase {
815
- subscription_id: string;
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[];
816
1034
  }
817
1035
  /** A successful checkout. `status` is always `"succeeded"` on this event — never anything else. */
818
- interface CheckoutSucceededEvent extends SubscriptionWebhookEventBase {
1036
+ interface CheckoutSucceededEvent extends CheckoutWebhookEventBase {
819
1037
  event: "checkout.succeeded";
820
- /** Decimal string. Never coerced to a number — SDK-SPEC.md §9. */
821
- amount: string;
822
1038
  status: "succeeded";
823
1039
  }
824
1040
  /**
825
- * A failed checkout. `status` is always `"failed"` — the platform deliberately omits the specific
826
- * failure reason from this payload.
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.
827
1043
  */
828
- interface CheckoutFailedEvent extends SubscriptionWebhookEventBase {
1044
+ interface CheckoutFailedEvent extends CheckoutWebhookEventBase {
829
1045
  event: "checkout.failed";
830
- /** Decimal string. Never coerced to a number — SDK-SPEC.md §9. */
831
- amount: string;
832
1046
  status: "failed";
833
1047
  }
834
1048
  /**
@@ -837,8 +1051,9 @@ interface CheckoutFailedEvent extends SubscriptionWebhookEventBase {
837
1051
  * §9's prose still says `subscription.status.change`; that's the doc that's stale, not this type
838
1052
  * (docs/implementation-plan.md Ticket 0 item 2).
839
1053
  */
840
- interface SubscriptionStatusChangedEvent extends SubscriptionWebhookEventBase {
1054
+ interface SubscriptionStatusChangedEvent {
841
1055
  event: "subscription.status_changed";
1056
+ subscription_id: string;
842
1057
  previous_status: SubscriptionStatus;
843
1058
  current_status: SubscriptionStatus;
844
1059
  /** ISO 8601 timestamp. */
@@ -851,8 +1066,11 @@ interface ApiKeyWebhookEventBase {
851
1066
  name: string;
852
1067
  /** Never the real key — always pre-masked by the backend (e.g. `"su_key_ca9...bf9e"`). */
853
1068
  masked_key: string;
854
- /** `YYYY-MM-DD`, date-only — no time component, unlike `created_at`/`deleted_at`. */
855
- expires_at: string;
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;
856
1074
  /** ISO 8601 timestamp. */
857
1075
  created_at: string;
858
1076
  }
@@ -887,6 +1105,77 @@ type WebhookEvent = CheckoutSucceededEvent | CheckoutFailedEvent | SubscriptionS
887
1105
  */
888
1106
  type WebhookEventType = WebhookEvent["event"];
889
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
+
890
1179
  /**
891
1180
  * `client.products` (SDK-SPEC.md §5, §6; `openapi.yaml` `listProducts`). The only resource that
892
1181
  * works before KYC verification — no `KycRequiredError` case to handle here.
@@ -906,10 +1195,11 @@ declare class ProductsResource {
906
1195
 
907
1196
  /**
908
1197
  * `client.subscriptions` (SDK-SPEC.md §5, §6, §7; `openapi.yaml` `listSubscriptions`/
909
- * `createSubscription`/`cancelSubscription`/`updateBillingCycle`/`resumeSubscription`).
1198
+ * `retrieveSubscription`/`createSubscription`/`cancelSubscription`/`updateBillingCycle`/
1199
+ * `resumeSubscription`/`renewSubscription`).
910
1200
  *
911
- * `retrieve(id)` is deliberately **not** implemented — still blocked on a real sample response
912
- * from backend (docs/implementation-plan.md Ticket 4). Every other operation here is confirmed.
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`.
913
1203
  */
914
1204
  declare class SubscriptionsResource {
915
1205
  #private;
@@ -925,13 +1215,21 @@ declare class SubscriptionsResource {
925
1215
  */
926
1216
  autoPaging(params?: PageParams): AsyncIterableIterator<Subscription>;
927
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
+ *
928
1226
  * Creates a subscription in `pending_checkout` state and returns a checkout URL for the buyer
929
1227
  * to pay (SDK-SPEC.md §5). Redirect the buyer to `checkoutUrl`; the return is **not** proof of
930
1228
  * payment — learn the real outcome via the `checkout.succeeded`/`checkout.failed` webhooks.
931
1229
  *
932
- * Reuse behavior: an inactive/expired subscription for the same buyer + product + billing
933
- * period is reactivated rather than duplicated; only a currently `active` one triggers the
934
- * duplicate-subscription `ValidationError`.
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.
935
1233
  *
936
1234
  * Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
937
1235
  */
@@ -939,7 +1237,9 @@ declare class SubscriptionsResource {
939
1237
  /**
940
1238
  * Schedules cancellation for the end of the current billing period — **not** immediate
941
1239
  * (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.
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.
943
1243
  *
944
1244
  * Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
945
1245
  */
@@ -952,13 +1252,24 @@ declare class SubscriptionsResource {
952
1252
  */
953
1253
  updateBillingCycle(params: UpdateBillingCycleParams): Promise<MessageResponse>;
954
1254
  /**
955
- * Resumes a subscription. Confirmed public with backend (2026-08-18); the response shape
956
- * follows Swagger's `{ message }` example but — unlike Customers — isn't independently
957
- * confirmed, so treat it as likely-correct-but-unverified (docs/implementation-plan.md Ticket 4).
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()`.
958
1258
  *
959
1259
  * Not auto-retryable — writes never retry until idempotency ships (SDK-SPEC.md §8, §12).
960
1260
  */
961
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>;
962
1273
  }
963
1274
 
964
1275
  /**
@@ -983,14 +1294,15 @@ declare class CustomersResource {
983
1294
  */
984
1295
  retrieve(id: string): Promise<Customer>;
985
1296
  /**
986
- * Records a customer on the seller's account without opening a subscription. `phone` identifies
987
- * the buyer; the name, email and address are the seller's own copy and aren't shared with other
988
- * sellers.
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.
989
1301
  *
990
- * A phone the seller already holds updates that existing customer instead of creating a second
991
- * one (the API answers `200` rather than `201`; both resolve to the `Customer` here). That makes
992
- * this call safe for the caller to retry — but, like every write, the SDK never retries it
993
- * automatically (SDK-SPEC.md §8, §12).
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).
994
1306
  */
995
1307
  create(params: CreateCustomerParams): Promise<Customer>;
996
1308
  /**
@@ -1003,13 +1315,32 @@ declare class CustomersResource {
1003
1315
  }
1004
1316
 
1005
1317
  /**
1006
- * `client.webhooks` (SDK-SPEC.md §5, §9). Makes **no** network calls and stores no secret — the
1007
- * host application passes its own signing secret into every call. Verifies an inbound delivery
1008
- * genuinely came from SUQO and hasn't been tampered with or replayed; it does **not** parse the
1009
- * event body itself (see `models/WebhookEvent.ts` for why the event types stay snake_case).
1010
- *
1011
- * @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()`.
1012
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
+
1013
1344
  /** Options accepted by {@link WebhooksResource.verify}. */
1014
1345
  interface VerifyWebhookOptions {
1015
1346
  /**
@@ -1033,6 +1364,44 @@ interface VerifyWebhookOptions {
1033
1364
  toleranceSec?: number;
1034
1365
  }
1035
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>;
1036
1405
  /**
1037
1406
  * Verifies an inbound webhook delivery's signature. Returns `false` for any failure mode —
1038
1407
  * malformed signature, expired timestamp, or a genuine mismatch — never throws, so a caller
@@ -1083,10 +1452,9 @@ interface SuqoClientOptions {
1083
1452
  * else to configure in the common case (SDK-SPEC.md §2). Construction throws `SuqoConfigError`
1084
1453
  * immediately on a malformed key, or on a `baseUrl` override that disagrees with the key.
1085
1454
  *
1086
- * `.products`/`.subscriptions`/`.customers` all share this one instance's `HttpClient` — same
1087
- * `baseUrl`/`apiKey`/`timeout`/`maxRetries` for every call, regardless of which resource makes it.
1088
- * `.webhooks` is deliberately **not** wired to that shared `HttpClient` — it makes no network
1089
- * 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).
1090
1458
  */
1091
1459
  declare class SuqoClient {
1092
1460
  #private;
@@ -1096,7 +1464,12 @@ declare class SuqoClient {
1096
1464
  readonly subscriptions: SubscriptionsResource;
1097
1465
  /** List, retrieve, create and update the seller's customers (SDK-SPEC.md §5, §6). */
1098
1466
  readonly customers: CustomersResource;
1099
- /** Verify inbound webhook deliveries (SDK-SPEC.md §9). Makes no network call, needs no key. */
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
+ */
1100
1473
  readonly webhooks: WebhooksResource;
1101
1474
  constructor(options: SuqoClientOptions);
1102
1475
  /** `"sandbox" | "live"` — inferred from the key prefix, never selected explicitly (SDK-SPEC.md §2). */
@@ -1118,6 +1491,6 @@ declare class SuqoClient {
1118
1491
  * @packageDocumentation
1119
1492
  */
1120
1493
  /** SDK version, stamped into request headers (keep in sync with package.json). */
1121
- declare const VERSION = "1.1.0";
1494
+ declare const VERSION = "2.0.0";
1122
1495
 
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 };
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 };