@suqo/sdk 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -10,7 +10,7 @@
10
10
  interface SuqoErrorOptions {
11
11
  /** HTTP status code this error was mapped from, if any (absent for `SuqoConfigError`/`NetworkError` — there was no response). */
12
12
  status?: number;
13
- /** The raw, parsed response body this error was mapped from, if any. */
13
+ /** The response body this error was mapped from, if any: parsed JSON, or the raw text when it wasn't JSON. */
14
14
  rawBody?: unknown;
15
15
  /**
16
16
  * The backend's request id for this call, if the response included one — ties a failure to a
@@ -40,7 +40,7 @@ interface SuqoErrorOptions {
40
40
  declare class SuqoError extends Error {
41
41
  /** HTTP status code this error was mapped from, if any. */
42
42
  readonly status?: number;
43
- /** The raw, parsed response body this error was mapped from, if any. */
43
+ /** The response body this error was mapped from, if any: parsed JSON, or the raw text when it wasn't JSON. */
44
44
  readonly rawBody?: unknown;
45
45
  /** The backend's request id for this call, if one was returned. See {@link SuqoErrorOptions.requestId}. */
46
46
  readonly requestId?: string;
@@ -91,6 +91,11 @@ interface ValidationErrorOptions extends SuqoErrorOptions {
91
91
  * §7). The API answers with `{ "detail": "…" }` alone, e.g. a key that doesn't belong to the
92
92
  * account. A KYC-shaped 403 (with `status_code`) is {@link KycRequiredError} instead.
93
93
  *
94
+ * Also thrown for a 403 that isn't JSON at all — usually a firewall in front of the API (e.g.
95
+ * Cloudflare's `error code: 1010`, which blocks some HTTP clients by `User-Agent`). Its message is
96
+ * just `Request failed with status 403`; read {@link SuqoError.rawBody} (the page's text) for the
97
+ * real cause.
98
+ *
94
99
  * Named `PermissionDeniedError`, not `PermissionError`: the stem must be identical in every port
95
100
  * (SDK Naming Map R2, R6), and `PermissionError` is a Python builtin.
96
101
  */
@@ -157,9 +162,10 @@ interface HttpErrorInput {
157
162
  /** The response's HTTP status text, if available — used only for the generic fallback message. */
158
163
  statusText?: string;
159
164
  /**
160
- * The parsed response body, if the response had one and it parsed as JSON. Expected to be one
165
+ * The response body: parsed JSON when it parsed, otherwise the raw text. Expected to be one
161
166
  * of `openapi.yaml`'s three error shapes (`FieldError`, `DetailError`, `KycError`) — the shape
162
- * is detected here, never assumed from the status code alone.
167
+ * is detected here, never assumed from the status code alone. A non-JSON body (a proxy/WAF
168
+ * page) gets the generic status message, never a SUQO-specific one.
163
169
  */
164
170
  body?: unknown;
165
171
  /** The backend's request id for this call, if one was returned (nice-to-have — Ticket 0 item 3). */
@@ -190,7 +196,12 @@ interface HttpErrorInput {
190
196
  * ```ts
191
197
  * const response = await fetch(url);
192
198
  * if (!response.ok) {
193
- * throw mapHttpError({ status: response.status, body: await response.json().catch(() => undefined) });
199
+ * const text = await response.text();
200
+ * let body: unknown = text || undefined;
201
+ * try {
202
+ * body = JSON.parse(text); // a SUQO error body; a proxy/WAF page stays text
203
+ * } catch {}
204
+ * throw mapHttpError({ status: response.status, body });
194
205
  * }
195
206
  * ```
196
207
  */
@@ -946,6 +957,11 @@ interface CheckoutLineItem {
946
957
  imageUrls?: string[];
947
958
  /** Partner-priced items only. */
948
959
  planName?: string | null;
960
+ /**
961
+ * The subscription this line pays for — on every item, new purchase or renewal. Absent only on
962
+ * sessions created before the API added it.
963
+ */
964
+ subscriptionId?: string;
949
965
  }
950
966
  /** The seller shown on a {@link CheckoutSession} (`openapi.yaml` `CheckoutSeller`). */
951
967
  interface CheckoutSeller {
@@ -1015,7 +1031,12 @@ interface CheckoutEventLineItem {
1015
1031
  image_urls?: string[];
1016
1032
  /** Partner-priced items only. */
1017
1033
  plan_name?: string | null;
1018
- /** Only on a payment opened by `subscriptions.renew()`: the subscription being renewed. */
1034
+ /**
1035
+ * The subscription this item pays for. Every item in a checkout session carries its own —
1036
+ * catalogue or partner-priced, Test or Live. Grant access by this, not a top-level field.
1037
+ * On `checkout.failed` it is a placeholder subscription that never activates (usually reused
1038
+ * if the buyer retries). Optional because payments made before the API added it lack it.
1039
+ */
1019
1040
  subscription_id?: string;
1020
1041
  }
1021
1042
  /**
@@ -1491,6 +1512,6 @@ declare class SuqoClient {
1491
1512
  * @packageDocumentation
1492
1513
  */
1493
1514
  /** SDK version, stamped into request headers (keep in sync with package.json). */
1494
- declare const VERSION = "2.0.0";
1515
+ declare const VERSION = "2.1.0";
1495
1516
 
1496
1517
  export { type ApiKeyCreatedEvent, type ApiKeyDeletedEvent, type ApiKeyExpiredEvent, type ApiKeyExpiringSoonEvent, AuthenticationError, type BillingPeriod, type CatalogueItemInput, type CheckoutFailedEvent, type CheckoutItemInput, type CheckoutLineItem, type CheckoutSeller, type CheckoutSession, type CheckoutSessionResponse, type CheckoutSucceededEvent, type CreateCheckoutSessionParams, type CreateCustomerParams, type CreateSubscriptionParams, type CreateSubscriptionResponse, type CreateWebhookParams, type Customer, type CustomerInput, type CustomerInputBilling, type CustomerInputShipping, type FieldErrors, type HttpErrorInput, KycRequiredError, type KycRequiredErrorOptions, type MessageResponse, NetworkError, NotFoundError, type Offer, type Page, type PageParams, type PartnerPricedItemInput, PermissionDeniedError, type Plan, type Product, type ProductImage, type ProductVat, RateLimitError, type RateLimitErrorOptions, type ReplaceWebhookParams, ServerError, type Subscription, type SubscriptionCustomer, type SubscriptionCustomerBilling, type SubscriptionCustomerShipping, type SubscriptionPage, type SubscriptionProduct, SubscriptionStatus, type SubscriptionStatusChangedEvent, type SubscriptionStatusCounts, SuqoClient, type SuqoClientOptions, SuqoConfigError, type SuqoEnvironment, SuqoError, type SuqoErrorOptions, type UpdateBillingCycleParams, type UpdateCustomerParams, type UpdateWebhookParams, VERSION, ValidationError, type ValidationErrorOptions, type VerifyWebhookOptions, type Webhook, type WebhookEvent, type WebhookEventType, type WebhookSecret, bridgeAutoPaging, deserializePage, listAll, mapHttpError, toPageQuery };
package/dist/index.d.ts CHANGED
@@ -10,7 +10,7 @@
10
10
  interface SuqoErrorOptions {
11
11
  /** HTTP status code this error was mapped from, if any (absent for `SuqoConfigError`/`NetworkError` — there was no response). */
12
12
  status?: number;
13
- /** The raw, parsed response body this error was mapped from, if any. */
13
+ /** The response body this error was mapped from, if any: parsed JSON, or the raw text when it wasn't JSON. */
14
14
  rawBody?: unknown;
15
15
  /**
16
16
  * The backend's request id for this call, if the response included one — ties a failure to a
@@ -40,7 +40,7 @@ interface SuqoErrorOptions {
40
40
  declare class SuqoError extends Error {
41
41
  /** HTTP status code this error was mapped from, if any. */
42
42
  readonly status?: number;
43
- /** The raw, parsed response body this error was mapped from, if any. */
43
+ /** The response body this error was mapped from, if any: parsed JSON, or the raw text when it wasn't JSON. */
44
44
  readonly rawBody?: unknown;
45
45
  /** The backend's request id for this call, if one was returned. See {@link SuqoErrorOptions.requestId}. */
46
46
  readonly requestId?: string;
@@ -91,6 +91,11 @@ interface ValidationErrorOptions extends SuqoErrorOptions {
91
91
  * §7). The API answers with `{ "detail": "…" }` alone, e.g. a key that doesn't belong to the
92
92
  * account. A KYC-shaped 403 (with `status_code`) is {@link KycRequiredError} instead.
93
93
  *
94
+ * Also thrown for a 403 that isn't JSON at all — usually a firewall in front of the API (e.g.
95
+ * Cloudflare's `error code: 1010`, which blocks some HTTP clients by `User-Agent`). Its message is
96
+ * just `Request failed with status 403`; read {@link SuqoError.rawBody} (the page's text) for the
97
+ * real cause.
98
+ *
94
99
  * Named `PermissionDeniedError`, not `PermissionError`: the stem must be identical in every port
95
100
  * (SDK Naming Map R2, R6), and `PermissionError` is a Python builtin.
96
101
  */
@@ -157,9 +162,10 @@ interface HttpErrorInput {
157
162
  /** The response's HTTP status text, if available — used only for the generic fallback message. */
158
163
  statusText?: string;
159
164
  /**
160
- * The parsed response body, if the response had one and it parsed as JSON. Expected to be one
165
+ * The response body: parsed JSON when it parsed, otherwise the raw text. Expected to be one
161
166
  * of `openapi.yaml`'s three error shapes (`FieldError`, `DetailError`, `KycError`) — the shape
162
- * is detected here, never assumed from the status code alone.
167
+ * is detected here, never assumed from the status code alone. A non-JSON body (a proxy/WAF
168
+ * page) gets the generic status message, never a SUQO-specific one.
163
169
  */
164
170
  body?: unknown;
165
171
  /** The backend's request id for this call, if one was returned (nice-to-have — Ticket 0 item 3). */
@@ -190,7 +196,12 @@ interface HttpErrorInput {
190
196
  * ```ts
191
197
  * const response = await fetch(url);
192
198
  * if (!response.ok) {
193
- * throw mapHttpError({ status: response.status, body: await response.json().catch(() => undefined) });
199
+ * const text = await response.text();
200
+ * let body: unknown = text || undefined;
201
+ * try {
202
+ * body = JSON.parse(text); // a SUQO error body; a proxy/WAF page stays text
203
+ * } catch {}
204
+ * throw mapHttpError({ status: response.status, body });
194
205
  * }
195
206
  * ```
196
207
  */
@@ -946,6 +957,11 @@ interface CheckoutLineItem {
946
957
  imageUrls?: string[];
947
958
  /** Partner-priced items only. */
948
959
  planName?: string | null;
960
+ /**
961
+ * The subscription this line pays for — on every item, new purchase or renewal. Absent only on
962
+ * sessions created before the API added it.
963
+ */
964
+ subscriptionId?: string;
949
965
  }
950
966
  /** The seller shown on a {@link CheckoutSession} (`openapi.yaml` `CheckoutSeller`). */
951
967
  interface CheckoutSeller {
@@ -1015,7 +1031,12 @@ interface CheckoutEventLineItem {
1015
1031
  image_urls?: string[];
1016
1032
  /** Partner-priced items only. */
1017
1033
  plan_name?: string | null;
1018
- /** Only on a payment opened by `subscriptions.renew()`: the subscription being renewed. */
1034
+ /**
1035
+ * The subscription this item pays for. Every item in a checkout session carries its own —
1036
+ * catalogue or partner-priced, Test or Live. Grant access by this, not a top-level field.
1037
+ * On `checkout.failed` it is a placeholder subscription that never activates (usually reused
1038
+ * if the buyer retries). Optional because payments made before the API added it lack it.
1039
+ */
1019
1040
  subscription_id?: string;
1020
1041
  }
1021
1042
  /**
@@ -1491,6 +1512,6 @@ declare class SuqoClient {
1491
1512
  * @packageDocumentation
1492
1513
  */
1493
1514
  /** SDK version, stamped into request headers (keep in sync with package.json). */
1494
- declare const VERSION = "2.0.0";
1515
+ declare const VERSION = "2.1.0";
1495
1516
 
1496
1517
  export { type ApiKeyCreatedEvent, type ApiKeyDeletedEvent, type ApiKeyExpiredEvent, type ApiKeyExpiringSoonEvent, AuthenticationError, type BillingPeriod, type CatalogueItemInput, type CheckoutFailedEvent, type CheckoutItemInput, type CheckoutLineItem, type CheckoutSeller, type CheckoutSession, type CheckoutSessionResponse, type CheckoutSucceededEvent, type CreateCheckoutSessionParams, type CreateCustomerParams, type CreateSubscriptionParams, type CreateSubscriptionResponse, type CreateWebhookParams, type Customer, type CustomerInput, type CustomerInputBilling, type CustomerInputShipping, type FieldErrors, type HttpErrorInput, KycRequiredError, type KycRequiredErrorOptions, type MessageResponse, NetworkError, NotFoundError, type Offer, type Page, type PageParams, type PartnerPricedItemInput, PermissionDeniedError, type Plan, type Product, type ProductImage, type ProductVat, RateLimitError, type RateLimitErrorOptions, type ReplaceWebhookParams, ServerError, type Subscription, type SubscriptionCustomer, type SubscriptionCustomerBilling, type SubscriptionCustomerShipping, type SubscriptionPage, type SubscriptionProduct, SubscriptionStatus, type SubscriptionStatusChangedEvent, type SubscriptionStatusCounts, SuqoClient, type SuqoClientOptions, SuqoConfigError, type SuqoEnvironment, SuqoError, type SuqoErrorOptions, type UpdateBillingCycleParams, type UpdateCustomerParams, type UpdateWebhookParams, VERSION, ValidationError, type ValidationErrorOptions, type VerifyWebhookOptions, type Webhook, type WebhookEvent, type WebhookEventType, type WebhookSecret, bridgeAutoPaging, deserializePage, listAll, mapHttpError, toPageQuery };
package/dist/index.js CHANGED
@@ -94,6 +94,7 @@ function mapHttpError(input) {
94
94
  const { status, statusText, body, requestId, retryAfter } = input;
95
95
  const fallbackMessage = `Request failed with status ${status}${statusText ? ` (${statusText})` : ""}`;
96
96
  const base = { status, rawBody: body, ...requestId !== void 0 ? { requestId } : {} };
97
+ const fallback = (suqoMessage) => typeof body === "string" ? fallbackMessage : suqoMessage;
97
98
  switch (status) {
98
99
  case 401:
99
100
  return new AuthenticationError(messageFrom(body, fallbackMessage), base);
@@ -102,7 +103,7 @@ function mapHttpError(input) {
102
103
  const message = messageFrom(body, "KYC verification needed to perform this action.");
103
104
  return new KycRequiredError(message, { ...base, kycStatus: body.status_code });
104
105
  }
105
- return new PermissionDeniedError(messageFrom(body, "You do not have permission to perform this action."), base);
106
+ return new PermissionDeniedError(messageFrom(body, fallback("You do not have permission to perform this action.")), base);
106
107
  }
107
108
  case 400: {
108
109
  if (isDetailShaped(body)) {
@@ -111,10 +112,10 @@ function mapHttpError(input) {
111
112
  if (isMessageList(body)) {
112
113
  return new ValidationError(body.join(" "), { ...base, fieldErrors: {} });
113
114
  }
114
- return new ValidationError("Validation failed.", { ...base, fieldErrors: fieldErrorsFrom(body) });
115
+ return new ValidationError(fallback("Validation failed."), { ...base, fieldErrors: fieldErrorsFrom(body) });
115
116
  }
116
117
  case 404:
117
- return new NotFoundError(messageFrom(body, "Not found."), base);
118
+ return new NotFoundError(messageFrom(body, fallback("Not found.")), base);
118
119
  case 429:
119
120
  return new RateLimitError(messageFrom(body, fallbackMessage), {
120
121
  ...base,
@@ -263,13 +264,13 @@ function combineSignals(signals) {
263
264
  function defaultSleep(ms) {
264
265
  return new Promise((resolve) => setTimeout(resolve, ms));
265
266
  }
266
- async function parseJsonBody(response) {
267
+ async function parseJsonBody(response, keepText = false) {
267
268
  const text = await response.text();
268
269
  if (text.length === 0) return void 0;
269
270
  try {
270
271
  return JSON.parse(text);
271
272
  } catch {
272
- return void 0;
273
+ return keepText ? text : void 0;
273
274
  }
274
275
  }
275
276
  function toNetworkError(cause, timeoutMs, callerCancelled) {
@@ -325,7 +326,7 @@ var HttpClient = class {
325
326
  if (response.ok) {
326
327
  return await parseJsonBody(response);
327
328
  }
328
- const body = await parseJsonBody(response);
329
+ const body = await parseJsonBody(response, true);
329
330
  const retryAfter = parseRetryAfterMs(response.headers.get("Retry-After")) ?? (response.status === 429 ? parseRetryAfterDetailMs(body) : void 0);
330
331
  if (!isLastAttempt && retryable && isRetryableFailure({ networkError: false, status: response.status })) {
331
332
  await this.#sleepOrAbort(retryAfter ?? backoffDelayMs(attempt - 1), options.signal, timeoutMs);
@@ -918,7 +919,9 @@ function deserializeLineItem(wire) {
918
919
  nextPaymentDue: wire.next_payment_due ?? null,
919
920
  // Each kind carries one of these and not the other, so they stay absent rather than null.
920
921
  ...wire.image_urls !== void 0 ? { imageUrls: wire.image_urls } : {},
921
- ...wire.plan_name !== void 0 ? { planName: wire.plan_name } : {}
922
+ ...wire.plan_name !== void 0 ? { planName: wire.plan_name } : {},
923
+ // Every item carries it; absent (not null) only on sessions created before the API added it.
924
+ ...wire.subscription_id !== void 0 ? { subscriptionId: wire.subscription_id } : {}
922
925
  };
923
926
  }
924
927
  function deserializeCheckoutSession(wire) {
@@ -1181,7 +1184,7 @@ var SuqoClient = class {
1181
1184
  };
1182
1185
 
1183
1186
  // src/index.ts
1184
- var VERSION = "2.0.0";
1187
+ var VERSION = "2.1.0";
1185
1188
 
1186
1189
  export { AuthenticationError, KycRequiredError, NetworkError, NotFoundError, PermissionDeniedError, RateLimitError, ServerError, SubscriptionStatus, SuqoClient, SuqoConfigError, SuqoError, VERSION, ValidationError, bridgeAutoPaging, deserializePage, listAll, mapHttpError, toPageQuery };
1187
1190
  //# sourceMappingURL=index.js.map