@usehercules/sdk 1.7.0 → 1.8.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.
Files changed (201) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +17 -16
  3. package/package.json +1 -1
  4. package/resources/beta/beta.d.mts +4 -4
  5. package/resources/beta/beta.d.mts.map +1 -1
  6. package/resources/beta/beta.d.ts +4 -4
  7. package/resources/beta/beta.d.ts.map +1 -1
  8. package/resources/beta/beta.js +4 -4
  9. package/resources/beta/beta.js.map +1 -1
  10. package/resources/beta/beta.mjs +4 -4
  11. package/resources/beta/beta.mjs.map +1 -1
  12. package/resources/beta/commerce/commerce.d.mts +201 -0
  13. package/resources/beta/commerce/commerce.d.mts.map +1 -0
  14. package/resources/beta/commerce/commerce.d.ts +201 -0
  15. package/resources/beta/commerce/commerce.d.ts.map +1 -0
  16. package/resources/beta/{pay/pay.js → commerce/commerce.js} +10 -14
  17. package/resources/beta/commerce/commerce.js.map +1 -0
  18. package/resources/beta/{pay/pay.mjs → commerce/commerce.mjs} +8 -12
  19. package/resources/beta/commerce/commerce.mjs.map +1 -0
  20. package/resources/beta/commerce/coupons.d.mts +333 -0
  21. package/resources/beta/commerce/coupons.d.mts.map +1 -0
  22. package/resources/beta/commerce/coupons.d.ts +333 -0
  23. package/resources/beta/commerce/coupons.d.ts.map +1 -0
  24. package/resources/beta/{pay → commerce}/coupons.js +8 -5
  25. package/resources/beta/commerce/coupons.js.map +1 -0
  26. package/resources/beta/{pay → commerce}/coupons.mjs +8 -5
  27. package/resources/beta/commerce/coupons.mjs.map +1 -0
  28. package/resources/beta/commerce/customers.d.mts +407 -0
  29. package/resources/beta/commerce/customers.d.mts.map +1 -0
  30. package/resources/beta/commerce/customers.d.ts +407 -0
  31. package/resources/beta/commerce/customers.d.ts.map +1 -0
  32. package/resources/beta/{pay → commerce}/customers.js +9 -6
  33. package/resources/beta/commerce/customers.js.map +1 -0
  34. package/resources/beta/{pay → commerce}/customers.mjs +9 -6
  35. package/resources/beta/commerce/customers.mjs.map +1 -0
  36. package/resources/beta/commerce/index.d.mts +5 -0
  37. package/resources/beta/commerce/index.d.mts.map +1 -0
  38. package/resources/beta/commerce/index.d.ts +5 -0
  39. package/resources/beta/commerce/index.d.ts.map +1 -0
  40. package/resources/beta/{pay → commerce}/index.js +3 -5
  41. package/resources/beta/commerce/index.js.map +1 -0
  42. package/resources/beta/{pay → commerce}/index.mjs +1 -2
  43. package/resources/beta/commerce/index.mjs.map +1 -0
  44. package/resources/beta/commerce/products/index.d.mts +4 -0
  45. package/resources/beta/commerce/products/index.d.mts.map +1 -0
  46. package/resources/beta/commerce/products/index.d.ts +4 -0
  47. package/resources/beta/commerce/products/index.d.ts.map +1 -0
  48. package/resources/beta/{pay → commerce}/products/index.js +3 -3
  49. package/resources/beta/commerce/products/index.js.map +1 -0
  50. package/resources/beta/{pay → commerce}/products/index.mjs +1 -1
  51. package/resources/beta/commerce/products/index.mjs.map +1 -0
  52. package/resources/beta/commerce/products/products.d.mts +967 -0
  53. package/resources/beta/commerce/products/products.d.mts.map +1 -0
  54. package/resources/beta/commerce/products/products.d.ts +967 -0
  55. package/resources/beta/commerce/products/products.d.ts.map +1 -0
  56. package/resources/beta/{pay → commerce}/products/products.js +16 -12
  57. package/resources/beta/commerce/products/products.js.map +1 -0
  58. package/resources/beta/{pay → commerce}/products/products.mjs +16 -12
  59. package/resources/beta/commerce/products/products.mjs.map +1 -0
  60. package/resources/beta/commerce/products/resources.d.mts +160 -0
  61. package/resources/beta/commerce/products/resources.d.mts.map +1 -0
  62. package/resources/beta/commerce/products/resources.d.ts +160 -0
  63. package/resources/beta/commerce/products/resources.d.ts.map +1 -0
  64. package/resources/beta/commerce/products/resources.js +41 -0
  65. package/resources/beta/commerce/products/resources.js.map +1 -0
  66. package/resources/beta/commerce/products/resources.mjs +37 -0
  67. package/resources/beta/commerce/products/resources.mjs.map +1 -0
  68. package/resources/beta/commerce/products/variants.d.mts +798 -0
  69. package/resources/beta/commerce/products/variants.d.mts.map +1 -0
  70. package/resources/beta/commerce/products/variants.d.ts +798 -0
  71. package/resources/beta/commerce/products/variants.d.ts.map +1 -0
  72. package/resources/beta/{pay → commerce}/products/variants.js +5 -8
  73. package/resources/beta/commerce/products/variants.js.map +1 -0
  74. package/resources/beta/{pay → commerce}/products/variants.mjs +5 -8
  75. package/resources/beta/commerce/products/variants.mjs.map +1 -0
  76. package/resources/beta/commerce/products.d.mts.map +1 -0
  77. package/resources/beta/commerce/products.d.ts.map +1 -0
  78. package/resources/beta/commerce/products.js.map +1 -0
  79. package/resources/beta/commerce/products.mjs.map +1 -0
  80. package/resources/beta/commerce.d.mts +2 -0
  81. package/resources/beta/commerce.d.mts.map +1 -0
  82. package/resources/beta/commerce.d.ts +2 -0
  83. package/resources/beta/commerce.d.ts.map +1 -0
  84. package/resources/beta/{pay.js → commerce.js} +2 -2
  85. package/resources/beta/commerce.js.map +1 -0
  86. package/resources/beta/{pay.mjs → commerce.mjs} +2 -2
  87. package/resources/beta/commerce.mjs.map +1 -0
  88. package/resources/beta/index.d.mts +1 -1
  89. package/resources/beta/index.d.mts.map +1 -1
  90. package/resources/beta/index.d.ts +1 -1
  91. package/resources/beta/index.d.ts.map +1 -1
  92. package/resources/beta/index.js +3 -3
  93. package/resources/beta/index.js.map +1 -1
  94. package/resources/beta/index.mjs +1 -1
  95. package/resources/beta/index.mjs.map +1 -1
  96. package/resources/push-notifications/push-notifications.d.mts +8 -9
  97. package/resources/push-notifications/push-notifications.d.mts.map +1 -1
  98. package/resources/push-notifications/push-notifications.d.ts +8 -9
  99. package/resources/push-notifications/push-notifications.d.ts.map +1 -1
  100. package/resources/push-notifications/push-notifications.js +5 -6
  101. package/resources/push-notifications/push-notifications.js.map +1 -1
  102. package/resources/push-notifications/push-notifications.mjs +5 -6
  103. package/resources/push-notifications/push-notifications.mjs.map +1 -1
  104. package/src/resources/beta/beta.ts +18 -18
  105. package/src/resources/beta/{pay/pay.ts → commerce/commerce.ts} +82 -85
  106. package/src/resources/beta/commerce/coupons.ts +440 -0
  107. package/src/resources/beta/commerce/customers.ts +532 -0
  108. package/src/resources/beta/commerce/index.ts +47 -0
  109. package/src/resources/beta/commerce/products/index.ts +37 -0
  110. package/src/resources/beta/commerce/products/products.ts +1199 -0
  111. package/src/resources/beta/commerce/products/resources.ts +213 -0
  112. package/src/resources/beta/commerce/products/variants.ts +984 -0
  113. package/src/resources/beta/{pay.ts → commerce.ts} +1 -1
  114. package/src/resources/beta/index.ts +8 -8
  115. package/src/resources/push-notifications/push-notifications.ts +8 -9
  116. package/src/version.ts +1 -1
  117. package/version.d.mts +1 -1
  118. package/version.d.ts +1 -1
  119. package/version.js +1 -1
  120. package/version.mjs +1 -1
  121. package/resources/beta/pay/coupons.d.mts +0 -156
  122. package/resources/beta/pay/coupons.d.mts.map +0 -1
  123. package/resources/beta/pay/coupons.d.ts +0 -156
  124. package/resources/beta/pay/coupons.d.ts.map +0 -1
  125. package/resources/beta/pay/coupons.js.map +0 -1
  126. package/resources/beta/pay/coupons.mjs.map +0 -1
  127. package/resources/beta/pay/customers.d.mts +0 -160
  128. package/resources/beta/pay/customers.d.mts.map +0 -1
  129. package/resources/beta/pay/customers.d.ts +0 -160
  130. package/resources/beta/pay/customers.d.ts.map +0 -1
  131. package/resources/beta/pay/customers.js.map +0 -1
  132. package/resources/beta/pay/customers.mjs.map +0 -1
  133. package/resources/beta/pay/entitlements.d.mts +0 -76
  134. package/resources/beta/pay/entitlements.d.mts.map +0 -1
  135. package/resources/beta/pay/entitlements.d.ts +0 -76
  136. package/resources/beta/pay/entitlements.d.ts.map +0 -1
  137. package/resources/beta/pay/entitlements.js +0 -41
  138. package/resources/beta/pay/entitlements.js.map +0 -1
  139. package/resources/beta/pay/entitlements.mjs +0 -37
  140. package/resources/beta/pay/entitlements.mjs.map +0 -1
  141. package/resources/beta/pay/index.d.mts +0 -6
  142. package/resources/beta/pay/index.d.mts.map +0 -1
  143. package/resources/beta/pay/index.d.ts +0 -6
  144. package/resources/beta/pay/index.d.ts.map +0 -1
  145. package/resources/beta/pay/index.js.map +0 -1
  146. package/resources/beta/pay/index.mjs.map +0 -1
  147. package/resources/beta/pay/pay.d.mts +0 -206
  148. package/resources/beta/pay/pay.d.mts.map +0 -1
  149. package/resources/beta/pay/pay.d.ts +0 -206
  150. package/resources/beta/pay/pay.d.ts.map +0 -1
  151. package/resources/beta/pay/pay.js.map +0 -1
  152. package/resources/beta/pay/pay.mjs.map +0 -1
  153. package/resources/beta/pay/products/entitlements.d.mts +0 -53
  154. package/resources/beta/pay/products/entitlements.d.mts.map +0 -1
  155. package/resources/beta/pay/products/entitlements.d.ts +0 -53
  156. package/resources/beta/pay/products/entitlements.d.ts.map +0 -1
  157. package/resources/beta/pay/products/entitlements.js +0 -38
  158. package/resources/beta/pay/products/entitlements.js.map +0 -1
  159. package/resources/beta/pay/products/entitlements.mjs +0 -34
  160. package/resources/beta/pay/products/entitlements.mjs.map +0 -1
  161. package/resources/beta/pay/products/index.d.mts +0 -4
  162. package/resources/beta/pay/products/index.d.mts.map +0 -1
  163. package/resources/beta/pay/products/index.d.ts +0 -4
  164. package/resources/beta/pay/products/index.d.ts.map +0 -1
  165. package/resources/beta/pay/products/index.js.map +0 -1
  166. package/resources/beta/pay/products/index.mjs.map +0 -1
  167. package/resources/beta/pay/products/products.d.mts +0 -183
  168. package/resources/beta/pay/products/products.d.mts.map +0 -1
  169. package/resources/beta/pay/products/products.d.ts +0 -183
  170. package/resources/beta/pay/products/products.d.ts.map +0 -1
  171. package/resources/beta/pay/products/products.js.map +0 -1
  172. package/resources/beta/pay/products/products.mjs.map +0 -1
  173. package/resources/beta/pay/products/variants.d.mts +0 -206
  174. package/resources/beta/pay/products/variants.d.mts.map +0 -1
  175. package/resources/beta/pay/products/variants.d.ts +0 -206
  176. package/resources/beta/pay/products/variants.d.ts.map +0 -1
  177. package/resources/beta/pay/products/variants.js.map +0 -1
  178. package/resources/beta/pay/products/variants.mjs.map +0 -1
  179. package/resources/beta/pay/products.d.mts.map +0 -1
  180. package/resources/beta/pay/products.d.ts.map +0 -1
  181. package/resources/beta/pay/products.js.map +0 -1
  182. package/resources/beta/pay/products.mjs.map +0 -1
  183. package/resources/beta/pay.d.mts +0 -2
  184. package/resources/beta/pay.d.mts.map +0 -1
  185. package/resources/beta/pay.d.ts +0 -2
  186. package/resources/beta/pay.d.ts.map +0 -1
  187. package/resources/beta/pay.js.map +0 -1
  188. package/resources/beta/pay.mjs.map +0 -1
  189. package/src/resources/beta/pay/coupons.ts +0 -218
  190. package/src/resources/beta/pay/customers.ts +0 -229
  191. package/src/resources/beta/pay/entitlements.ts +0 -113
  192. package/src/resources/beta/pay/index.ts +0 -46
  193. package/src/resources/beta/pay/products/entitlements.ts +0 -93
  194. package/src/resources/beta/pay/products/index.ts +0 -28
  195. package/src/resources/beta/pay/products/products.ts +0 -280
  196. package/src/resources/beta/pay/products/variants.ts +0 -279
  197. /package/resources/beta/{pay → commerce}/products.d.mts +0 -0
  198. /package/resources/beta/{pay → commerce}/products.d.ts +0 -0
  199. /package/resources/beta/{pay → commerce}/products.js +0 -0
  200. /package/resources/beta/{pay → commerce}/products.mjs +0 -0
  201. /package/src/resources/beta/{pay → commerce}/products.ts +0 -0
@@ -0,0 +1,984 @@
1
+ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2
+
3
+ import { APIResource } from '../../../../core/resource';
4
+ import { APIPromise } from '../../../../core/api-promise';
5
+ import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../../../core/pagination';
6
+ import { RequestOptions } from '../../../../internal/request-options';
7
+ import { path } from '../../../../internal/utils/path';
8
+
9
+ export class Variants extends APIResource {
10
+ /**
11
+ * Creates a new variant with pricing for a product. Use variants to offer multiple
12
+ * pricing tiers or configurations (e.g., Basic at $10/month, Pro at $25/month). A
13
+ * Stripe Price is automatically created.
14
+ */
15
+ create(
16
+ productID: string,
17
+ body: VariantCreateParams,
18
+ options?: RequestOptions,
19
+ ): APIPromise<VariantCreateResponse> {
20
+ return this._client.post(path`/v1/commerce/products/${productID}/variants`, { body, ...options });
21
+ }
22
+
23
+ /**
24
+ * Updates an existing variant. Use this to modify the name, description, or active
25
+ * status. Pricing cannot be changed after creation—create a new variant instead.
26
+ */
27
+ update(
28
+ variantID: string,
29
+ params: VariantUpdateParams,
30
+ options?: RequestOptions,
31
+ ): APIPromise<VariantUpdateResponse> {
32
+ const { product_id, ...body } = params;
33
+ return this._client.patch(path`/v1/commerce/products/${product_id}/variants/${variantID}`, {
34
+ body,
35
+ ...options,
36
+ });
37
+ }
38
+
39
+ /**
40
+ * Retrieves all variants for a product. Variants represent different pricing tiers
41
+ * or configurations (e.g., Basic, Pro, Enterprise) within a single product.
42
+ */
43
+ list(
44
+ productID: string,
45
+ query: VariantListParams | null | undefined = {},
46
+ options?: RequestOptions,
47
+ ): PagePromise<VariantListResponsesCursorIDPage, VariantListResponse> {
48
+ return this._client.getAPIList(
49
+ path`/v1/commerce/products/${productID}/variants`,
50
+ CursorIDPage<VariantListResponse>,
51
+ { query, ...options },
52
+ );
53
+ }
54
+
55
+ /**
56
+ * Archives a variant, preventing new subscriptions. The associated Stripe Price is
57
+ * also archived. Existing subscriptions remain active.
58
+ */
59
+ archive(
60
+ variantID: string,
61
+ params: VariantArchiveParams,
62
+ options?: RequestOptions,
63
+ ): APIPromise<VariantArchiveResponse> {
64
+ const { product_id } = params;
65
+ return this._client.delete(path`/v1/commerce/products/${product_id}/variants/${variantID}`, options);
66
+ }
67
+
68
+ /**
69
+ * Retrieves a variant by ID. Returns the variant object including pricing details
70
+ * and status.
71
+ */
72
+ get(variantID: string, params: VariantGetParams, options?: RequestOptions): APIPromise<VariantGetResponse> {
73
+ const { product_id } = params;
74
+ return this._client.get(path`/v1/commerce/products/${product_id}/variants/${variantID}`, options);
75
+ }
76
+ }
77
+
78
+ export type VariantListResponsesCursorIDPage = CursorIDPage<VariantListResponse>;
79
+
80
+ /**
81
+ * A product variant representing a specific tier or configuration. Each variant
82
+ * has its own pricing. Variants allow a single product to have multiple pricing
83
+ * options (e.g., Basic, Pro, Enterprise tiers).
84
+ */
85
+ export interface VariantCreateResponse {
86
+ /**
87
+ * Unique identifier for the topic subscription
88
+ */
89
+ id: string;
90
+
91
+ /**
92
+ * Whether the variant is available for new purchases
93
+ */
94
+ active: boolean;
95
+
96
+ /**
97
+ * Timestamp when the variant was created
98
+ */
99
+ created: string;
100
+
101
+ /**
102
+ * Display name for the variant (e.g., Basic, Standard, Premium)
103
+ */
104
+ name: string;
105
+
106
+ /**
107
+ * Three-letter ISO currency code
108
+ */
109
+ currency?: string;
110
+
111
+ /**
112
+ * Price configuration for a product. Can be one-time or recurring (subscription).
113
+ */
114
+ default_price?: VariantCreateResponse.DefaultPrice | null;
115
+
116
+ /**
117
+ * Detailed description of what this variant includes
118
+ */
119
+ description?: string | null;
120
+
121
+ /**
122
+ * Media attachments (images, videos) for the variant
123
+ */
124
+ media?: Array<VariantCreateResponse.Media>;
125
+
126
+ /**
127
+ * Custom metadata for the variant
128
+ */
129
+ metadata?: { [key: string]: unknown };
130
+
131
+ /**
132
+ * Recurring billing configuration for subscription variants
133
+ */
134
+ recurring?: VariantCreateResponse.Recurring | null;
135
+
136
+ /**
137
+ * Price amount in the smallest currency unit (e.g., cents). 0 for free variants.
138
+ */
139
+ unit_amount?: number;
140
+ }
141
+
142
+ export namespace VariantCreateResponse {
143
+ /**
144
+ * Price configuration for a product. Can be one-time or recurring (subscription).
145
+ */
146
+ export interface DefaultPrice {
147
+ /**
148
+ * Unique identifier for the topic subscription
149
+ */
150
+ id: string;
151
+
152
+ /**
153
+ * How to handle the billing cycle when switching plans. 'now' resets to current
154
+ * time, 'unchanged' keeps the original anchor. Null for one-time prices.
155
+ */
156
+ billing_cycle_anchor: 'now' | 'unchanged' | null;
157
+
158
+ /**
159
+ * Three-letter ISO currency code (e.g., usd, eur)
160
+ */
161
+ currency: string;
162
+
163
+ /**
164
+ * Billing frequency for recurring prices: day, week, month, or year. Null for
165
+ * one-time prices.
166
+ */
167
+ interval: 'day' | 'week' | 'month' | 'year' | null;
168
+
169
+ /**
170
+ * Number of intervals between billings for recurring prices. Null for one-time
171
+ * prices.
172
+ */
173
+ interval_count: number | null;
174
+
175
+ /**
176
+ * How to handle prorations when switching plans. 'default' creates prorations,
177
+ * 'none' disables them. Null for one-time prices.
178
+ */
179
+ proration_behavior: 'default' | 'none' | null;
180
+
181
+ /**
182
+ * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
183
+ * billing period start. Null for one-time prices or to use Stripe's default.
184
+ */
185
+ proration_date: 'now' | 'start_of_period' | null;
186
+
187
+ /**
188
+ * Price type: one_time for single purchases, recurring for subscriptions
189
+ */
190
+ type: 'one_time' | 'recurring';
191
+
192
+ /**
193
+ * Price amount in the smallest currency unit (e.g., cents)
194
+ */
195
+ unit_amount: number | null;
196
+ }
197
+
198
+ /**
199
+ * Media attachment for products or variants
200
+ */
201
+ export interface Media {
202
+ /**
203
+ * Type of media: image, video, or external link
204
+ */
205
+ type: 'image' | 'video' | 'external';
206
+
207
+ /**
208
+ * URL of the media resource
209
+ */
210
+ url: string;
211
+ }
212
+
213
+ /**
214
+ * Recurring billing configuration for subscription variants
215
+ */
216
+ export interface Recurring {
217
+ /**
218
+ * Billing frequency: day, week, month, or year
219
+ */
220
+ interval: 'day' | 'week' | 'month' | 'year';
221
+
222
+ /**
223
+ * Number of intervals between billings
224
+ */
225
+ interval_count?: number;
226
+ }
227
+ }
228
+
229
+ /**
230
+ * A product variant representing a specific tier or configuration. Each variant
231
+ * has its own pricing. Variants allow a single product to have multiple pricing
232
+ * options (e.g., Basic, Pro, Enterprise tiers).
233
+ */
234
+ export interface VariantUpdateResponse {
235
+ /**
236
+ * Unique identifier for the topic subscription
237
+ */
238
+ id: string;
239
+
240
+ /**
241
+ * Whether the variant is available for new purchases
242
+ */
243
+ active: boolean;
244
+
245
+ /**
246
+ * Timestamp when the variant was created
247
+ */
248
+ created: string;
249
+
250
+ /**
251
+ * Display name for the variant (e.g., Basic, Standard, Premium)
252
+ */
253
+ name: string;
254
+
255
+ /**
256
+ * Three-letter ISO currency code
257
+ */
258
+ currency?: string;
259
+
260
+ /**
261
+ * Price configuration for a product. Can be one-time or recurring (subscription).
262
+ */
263
+ default_price?: VariantUpdateResponse.DefaultPrice | null;
264
+
265
+ /**
266
+ * Detailed description of what this variant includes
267
+ */
268
+ description?: string | null;
269
+
270
+ /**
271
+ * Media attachments (images, videos) for the variant
272
+ */
273
+ media?: Array<VariantUpdateResponse.Media>;
274
+
275
+ /**
276
+ * Custom metadata for the variant
277
+ */
278
+ metadata?: { [key: string]: unknown };
279
+
280
+ /**
281
+ * Recurring billing configuration for subscription variants
282
+ */
283
+ recurring?: VariantUpdateResponse.Recurring | null;
284
+
285
+ /**
286
+ * Price amount in the smallest currency unit (e.g., cents). 0 for free variants.
287
+ */
288
+ unit_amount?: number;
289
+ }
290
+
291
+ export namespace VariantUpdateResponse {
292
+ /**
293
+ * Price configuration for a product. Can be one-time or recurring (subscription).
294
+ */
295
+ export interface DefaultPrice {
296
+ /**
297
+ * Unique identifier for the topic subscription
298
+ */
299
+ id: string;
300
+
301
+ /**
302
+ * How to handle the billing cycle when switching plans. 'now' resets to current
303
+ * time, 'unchanged' keeps the original anchor. Null for one-time prices.
304
+ */
305
+ billing_cycle_anchor: 'now' | 'unchanged' | null;
306
+
307
+ /**
308
+ * Three-letter ISO currency code (e.g., usd, eur)
309
+ */
310
+ currency: string;
311
+
312
+ /**
313
+ * Billing frequency for recurring prices: day, week, month, or year. Null for
314
+ * one-time prices.
315
+ */
316
+ interval: 'day' | 'week' | 'month' | 'year' | null;
317
+
318
+ /**
319
+ * Number of intervals between billings for recurring prices. Null for one-time
320
+ * prices.
321
+ */
322
+ interval_count: number | null;
323
+
324
+ /**
325
+ * How to handle prorations when switching plans. 'default' creates prorations,
326
+ * 'none' disables them. Null for one-time prices.
327
+ */
328
+ proration_behavior: 'default' | 'none' | null;
329
+
330
+ /**
331
+ * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
332
+ * billing period start. Null for one-time prices or to use Stripe's default.
333
+ */
334
+ proration_date: 'now' | 'start_of_period' | null;
335
+
336
+ /**
337
+ * Price type: one_time for single purchases, recurring for subscriptions
338
+ */
339
+ type: 'one_time' | 'recurring';
340
+
341
+ /**
342
+ * Price amount in the smallest currency unit (e.g., cents)
343
+ */
344
+ unit_amount: number | null;
345
+ }
346
+
347
+ /**
348
+ * Media attachment for products or variants
349
+ */
350
+ export interface Media {
351
+ /**
352
+ * Type of media: image, video, or external link
353
+ */
354
+ type: 'image' | 'video' | 'external';
355
+
356
+ /**
357
+ * URL of the media resource
358
+ */
359
+ url: string;
360
+ }
361
+
362
+ /**
363
+ * Recurring billing configuration for subscription variants
364
+ */
365
+ export interface Recurring {
366
+ /**
367
+ * Billing frequency: day, week, month, or year
368
+ */
369
+ interval: 'day' | 'week' | 'month' | 'year';
370
+
371
+ /**
372
+ * Number of intervals between billings
373
+ */
374
+ interval_count?: number;
375
+ }
376
+ }
377
+
378
+ /**
379
+ * A product variant representing a specific tier or configuration. Each variant
380
+ * has its own pricing. Variants allow a single product to have multiple pricing
381
+ * options (e.g., Basic, Pro, Enterprise tiers).
382
+ */
383
+ export interface VariantListResponse {
384
+ /**
385
+ * Unique identifier for the topic subscription
386
+ */
387
+ id: string;
388
+
389
+ /**
390
+ * Whether the variant is available for new purchases
391
+ */
392
+ active: boolean;
393
+
394
+ /**
395
+ * Timestamp when the variant was created
396
+ */
397
+ created: string;
398
+
399
+ /**
400
+ * Display name for the variant (e.g., Basic, Standard, Premium)
401
+ */
402
+ name: string;
403
+
404
+ /**
405
+ * Three-letter ISO currency code
406
+ */
407
+ currency?: string;
408
+
409
+ /**
410
+ * Price configuration for a product. Can be one-time or recurring (subscription).
411
+ */
412
+ default_price?: VariantListResponse.DefaultPrice | null;
413
+
414
+ /**
415
+ * Detailed description of what this variant includes
416
+ */
417
+ description?: string | null;
418
+
419
+ /**
420
+ * Media attachments (images, videos) for the variant
421
+ */
422
+ media?: Array<VariantListResponse.Media>;
423
+
424
+ /**
425
+ * Custom metadata for the variant
426
+ */
427
+ metadata?: { [key: string]: unknown };
428
+
429
+ /**
430
+ * Recurring billing configuration for subscription variants
431
+ */
432
+ recurring?: VariantListResponse.Recurring | null;
433
+
434
+ /**
435
+ * Price amount in the smallest currency unit (e.g., cents). 0 for free variants.
436
+ */
437
+ unit_amount?: number;
438
+ }
439
+
440
+ export namespace VariantListResponse {
441
+ /**
442
+ * Price configuration for a product. Can be one-time or recurring (subscription).
443
+ */
444
+ export interface DefaultPrice {
445
+ /**
446
+ * Unique identifier for the topic subscription
447
+ */
448
+ id: string;
449
+
450
+ /**
451
+ * How to handle the billing cycle when switching plans. 'now' resets to current
452
+ * time, 'unchanged' keeps the original anchor. Null for one-time prices.
453
+ */
454
+ billing_cycle_anchor: 'now' | 'unchanged' | null;
455
+
456
+ /**
457
+ * Three-letter ISO currency code (e.g., usd, eur)
458
+ */
459
+ currency: string;
460
+
461
+ /**
462
+ * Billing frequency for recurring prices: day, week, month, or year. Null for
463
+ * one-time prices.
464
+ */
465
+ interval: 'day' | 'week' | 'month' | 'year' | null;
466
+
467
+ /**
468
+ * Number of intervals between billings for recurring prices. Null for one-time
469
+ * prices.
470
+ */
471
+ interval_count: number | null;
472
+
473
+ /**
474
+ * How to handle prorations when switching plans. 'default' creates prorations,
475
+ * 'none' disables them. Null for one-time prices.
476
+ */
477
+ proration_behavior: 'default' | 'none' | null;
478
+
479
+ /**
480
+ * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
481
+ * billing period start. Null for one-time prices or to use Stripe's default.
482
+ */
483
+ proration_date: 'now' | 'start_of_period' | null;
484
+
485
+ /**
486
+ * Price type: one_time for single purchases, recurring for subscriptions
487
+ */
488
+ type: 'one_time' | 'recurring';
489
+
490
+ /**
491
+ * Price amount in the smallest currency unit (e.g., cents)
492
+ */
493
+ unit_amount: number | null;
494
+ }
495
+
496
+ /**
497
+ * Media attachment for products or variants
498
+ */
499
+ export interface Media {
500
+ /**
501
+ * Type of media: image, video, or external link
502
+ */
503
+ type: 'image' | 'video' | 'external';
504
+
505
+ /**
506
+ * URL of the media resource
507
+ */
508
+ url: string;
509
+ }
510
+
511
+ /**
512
+ * Recurring billing configuration for subscription variants
513
+ */
514
+ export interface Recurring {
515
+ /**
516
+ * Billing frequency: day, week, month, or year
517
+ */
518
+ interval: 'day' | 'week' | 'month' | 'year';
519
+
520
+ /**
521
+ * Number of intervals between billings
522
+ */
523
+ interval_count?: number;
524
+ }
525
+ }
526
+
527
+ /**
528
+ * A product variant representing a specific tier or configuration. Each variant
529
+ * has its own pricing. Variants allow a single product to have multiple pricing
530
+ * options (e.g., Basic, Pro, Enterprise tiers).
531
+ */
532
+ export interface VariantArchiveResponse {
533
+ /**
534
+ * Unique identifier for the topic subscription
535
+ */
536
+ id: string;
537
+
538
+ /**
539
+ * Whether the variant is available for new purchases
540
+ */
541
+ active: boolean;
542
+
543
+ /**
544
+ * Timestamp when the variant was created
545
+ */
546
+ created: string;
547
+
548
+ /**
549
+ * Display name for the variant (e.g., Basic, Standard, Premium)
550
+ */
551
+ name: string;
552
+
553
+ /**
554
+ * Three-letter ISO currency code
555
+ */
556
+ currency?: string;
557
+
558
+ /**
559
+ * Price configuration for a product. Can be one-time or recurring (subscription).
560
+ */
561
+ default_price?: VariantArchiveResponse.DefaultPrice | null;
562
+
563
+ /**
564
+ * Detailed description of what this variant includes
565
+ */
566
+ description?: string | null;
567
+
568
+ /**
569
+ * Media attachments (images, videos) for the variant
570
+ */
571
+ media?: Array<VariantArchiveResponse.Media>;
572
+
573
+ /**
574
+ * Custom metadata for the variant
575
+ */
576
+ metadata?: { [key: string]: unknown };
577
+
578
+ /**
579
+ * Recurring billing configuration for subscription variants
580
+ */
581
+ recurring?: VariantArchiveResponse.Recurring | null;
582
+
583
+ /**
584
+ * Price amount in the smallest currency unit (e.g., cents). 0 for free variants.
585
+ */
586
+ unit_amount?: number;
587
+ }
588
+
589
+ export namespace VariantArchiveResponse {
590
+ /**
591
+ * Price configuration for a product. Can be one-time or recurring (subscription).
592
+ */
593
+ export interface DefaultPrice {
594
+ /**
595
+ * Unique identifier for the topic subscription
596
+ */
597
+ id: string;
598
+
599
+ /**
600
+ * How to handle the billing cycle when switching plans. 'now' resets to current
601
+ * time, 'unchanged' keeps the original anchor. Null for one-time prices.
602
+ */
603
+ billing_cycle_anchor: 'now' | 'unchanged' | null;
604
+
605
+ /**
606
+ * Three-letter ISO currency code (e.g., usd, eur)
607
+ */
608
+ currency: string;
609
+
610
+ /**
611
+ * Billing frequency for recurring prices: day, week, month, or year. Null for
612
+ * one-time prices.
613
+ */
614
+ interval: 'day' | 'week' | 'month' | 'year' | null;
615
+
616
+ /**
617
+ * Number of intervals between billings for recurring prices. Null for one-time
618
+ * prices.
619
+ */
620
+ interval_count: number | null;
621
+
622
+ /**
623
+ * How to handle prorations when switching plans. 'default' creates prorations,
624
+ * 'none' disables them. Null for one-time prices.
625
+ */
626
+ proration_behavior: 'default' | 'none' | null;
627
+
628
+ /**
629
+ * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
630
+ * billing period start. Null for one-time prices or to use Stripe's default.
631
+ */
632
+ proration_date: 'now' | 'start_of_period' | null;
633
+
634
+ /**
635
+ * Price type: one_time for single purchases, recurring for subscriptions
636
+ */
637
+ type: 'one_time' | 'recurring';
638
+
639
+ /**
640
+ * Price amount in the smallest currency unit (e.g., cents)
641
+ */
642
+ unit_amount: number | null;
643
+ }
644
+
645
+ /**
646
+ * Media attachment for products or variants
647
+ */
648
+ export interface Media {
649
+ /**
650
+ * Type of media: image, video, or external link
651
+ */
652
+ type: 'image' | 'video' | 'external';
653
+
654
+ /**
655
+ * URL of the media resource
656
+ */
657
+ url: string;
658
+ }
659
+
660
+ /**
661
+ * Recurring billing configuration for subscription variants
662
+ */
663
+ export interface Recurring {
664
+ /**
665
+ * Billing frequency: day, week, month, or year
666
+ */
667
+ interval: 'day' | 'week' | 'month' | 'year';
668
+
669
+ /**
670
+ * Number of intervals between billings
671
+ */
672
+ interval_count?: number;
673
+ }
674
+ }
675
+
676
+ /**
677
+ * A product variant representing a specific tier or configuration. Each variant
678
+ * has its own pricing. Variants allow a single product to have multiple pricing
679
+ * options (e.g., Basic, Pro, Enterprise tiers).
680
+ */
681
+ export interface VariantGetResponse {
682
+ /**
683
+ * Unique identifier for the topic subscription
684
+ */
685
+ id: string;
686
+
687
+ /**
688
+ * Whether the variant is available for new purchases
689
+ */
690
+ active: boolean;
691
+
692
+ /**
693
+ * Timestamp when the variant was created
694
+ */
695
+ created: string;
696
+
697
+ /**
698
+ * Display name for the variant (e.g., Basic, Standard, Premium)
699
+ */
700
+ name: string;
701
+
702
+ /**
703
+ * Three-letter ISO currency code
704
+ */
705
+ currency?: string;
706
+
707
+ /**
708
+ * Price configuration for a product. Can be one-time or recurring (subscription).
709
+ */
710
+ default_price?: VariantGetResponse.DefaultPrice | null;
711
+
712
+ /**
713
+ * Detailed description of what this variant includes
714
+ */
715
+ description?: string | null;
716
+
717
+ /**
718
+ * Media attachments (images, videos) for the variant
719
+ */
720
+ media?: Array<VariantGetResponse.Media>;
721
+
722
+ /**
723
+ * Custom metadata for the variant
724
+ */
725
+ metadata?: { [key: string]: unknown };
726
+
727
+ /**
728
+ * Recurring billing configuration for subscription variants
729
+ */
730
+ recurring?: VariantGetResponse.Recurring | null;
731
+
732
+ /**
733
+ * Price amount in the smallest currency unit (e.g., cents). 0 for free variants.
734
+ */
735
+ unit_amount?: number;
736
+ }
737
+
738
+ export namespace VariantGetResponse {
739
+ /**
740
+ * Price configuration for a product. Can be one-time or recurring (subscription).
741
+ */
742
+ export interface DefaultPrice {
743
+ /**
744
+ * Unique identifier for the topic subscription
745
+ */
746
+ id: string;
747
+
748
+ /**
749
+ * How to handle the billing cycle when switching plans. 'now' resets to current
750
+ * time, 'unchanged' keeps the original anchor. Null for one-time prices.
751
+ */
752
+ billing_cycle_anchor: 'now' | 'unchanged' | null;
753
+
754
+ /**
755
+ * Three-letter ISO currency code (e.g., usd, eur)
756
+ */
757
+ currency: string;
758
+
759
+ /**
760
+ * Billing frequency for recurring prices: day, week, month, or year. Null for
761
+ * one-time prices.
762
+ */
763
+ interval: 'day' | 'week' | 'month' | 'year' | null;
764
+
765
+ /**
766
+ * Number of intervals between billings for recurring prices. Null for one-time
767
+ * prices.
768
+ */
769
+ interval_count: number | null;
770
+
771
+ /**
772
+ * How to handle prorations when switching plans. 'default' creates prorations,
773
+ * 'none' disables them. Null for one-time prices.
774
+ */
775
+ proration_behavior: 'default' | 'none' | null;
776
+
777
+ /**
778
+ * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
779
+ * billing period start. Null for one-time prices or to use Stripe's default.
780
+ */
781
+ proration_date: 'now' | 'start_of_period' | null;
782
+
783
+ /**
784
+ * Price type: one_time for single purchases, recurring for subscriptions
785
+ */
786
+ type: 'one_time' | 'recurring';
787
+
788
+ /**
789
+ * Price amount in the smallest currency unit (e.g., cents)
790
+ */
791
+ unit_amount: number | null;
792
+ }
793
+
794
+ /**
795
+ * Media attachment for products or variants
796
+ */
797
+ export interface Media {
798
+ /**
799
+ * Type of media: image, video, or external link
800
+ */
801
+ type: 'image' | 'video' | 'external';
802
+
803
+ /**
804
+ * URL of the media resource
805
+ */
806
+ url: string;
807
+ }
808
+
809
+ /**
810
+ * Recurring billing configuration for subscription variants
811
+ */
812
+ export interface Recurring {
813
+ /**
814
+ * Billing frequency: day, week, month, or year
815
+ */
816
+ interval: 'day' | 'week' | 'month' | 'year';
817
+
818
+ /**
819
+ * Number of intervals between billings
820
+ */
821
+ interval_count?: number;
822
+ }
823
+ }
824
+
825
+ export interface VariantCreateParams {
826
+ /**
827
+ * Display name for the variant (e.g., Basic, Standard, Premium)
828
+ */
829
+ name: string;
830
+
831
+ /**
832
+ * Optional custom ID for the variant. If not provided, one will be generated.
833
+ */
834
+ id?: string;
835
+
836
+ /**
837
+ * Three-letter ISO currency code
838
+ */
839
+ currency?: string;
840
+
841
+ /**
842
+ * Detailed description of what this variant includes
843
+ */
844
+ description?: string;
845
+
846
+ /**
847
+ * Media attachments (images, videos) for the variant
848
+ */
849
+ media?: Array<VariantCreateParams.Media>;
850
+
851
+ /**
852
+ * Custom metadata for the variant
853
+ */
854
+ metadata?: { [key: string]: unknown };
855
+
856
+ /**
857
+ * Recurring billing configuration for subscription variants
858
+ */
859
+ recurring?: VariantCreateParams.Recurring;
860
+
861
+ /**
862
+ * Price amount in the smallest currency unit (e.g., cents). Use 0 for free
863
+ * variants.
864
+ */
865
+ unit_amount?: number;
866
+ }
867
+
868
+ export namespace VariantCreateParams {
869
+ /**
870
+ * Media attachment for products or variants
871
+ */
872
+ export interface Media {
873
+ /**
874
+ * Type of media: image, video, or external link
875
+ */
876
+ type: 'image' | 'video' | 'external';
877
+
878
+ /**
879
+ * URL of the media resource
880
+ */
881
+ url: string;
882
+ }
883
+
884
+ /**
885
+ * Recurring billing configuration for subscription variants
886
+ */
887
+ export interface Recurring {
888
+ /**
889
+ * Billing frequency: day, week, month, or year
890
+ */
891
+ interval: 'day' | 'week' | 'month' | 'year';
892
+
893
+ /**
894
+ * Number of intervals between billings
895
+ */
896
+ interval_count?: number;
897
+ }
898
+ }
899
+
900
+ export interface VariantUpdateParams {
901
+ /**
902
+ * Path param: The unique identifier of the product
903
+ */
904
+ product_id: string;
905
+
906
+ /**
907
+ * Body param: Whether the variant is available for new purchases
908
+ */
909
+ active?: boolean;
910
+
911
+ /**
912
+ * Body param: Detailed description of what this variant includes
913
+ */
914
+ description?: string;
915
+
916
+ /**
917
+ * Body param: Media attachments (images, videos) for the variant
918
+ */
919
+ media?: Array<VariantUpdateParams.Media>;
920
+
921
+ /**
922
+ * Body param: Custom metadata for the variant
923
+ */
924
+ metadata?: { [key: string]: unknown };
925
+
926
+ /**
927
+ * Body param: Display name for the variant
928
+ */
929
+ name?: string;
930
+ }
931
+
932
+ export namespace VariantUpdateParams {
933
+ /**
934
+ * Media attachment for products or variants
935
+ */
936
+ export interface Media {
937
+ /**
938
+ * Type of media: image, video, or external link
939
+ */
940
+ type: 'image' | 'video' | 'external';
941
+
942
+ /**
943
+ * URL of the media resource
944
+ */
945
+ url: string;
946
+ }
947
+ }
948
+
949
+ export interface VariantListParams extends CursorIDPageParams {
950
+ /**
951
+ * Filter by active status
952
+ */
953
+ active?: 'true' | 'false';
954
+ }
955
+
956
+ export interface VariantArchiveParams {
957
+ /**
958
+ * The unique identifier of the product
959
+ */
960
+ product_id: string;
961
+ }
962
+
963
+ export interface VariantGetParams {
964
+ /**
965
+ * The unique identifier of the product
966
+ */
967
+ product_id: string;
968
+ }
969
+
970
+ export declare namespace Variants {
971
+ export {
972
+ type VariantCreateResponse as VariantCreateResponse,
973
+ type VariantUpdateResponse as VariantUpdateResponse,
974
+ type VariantListResponse as VariantListResponse,
975
+ type VariantArchiveResponse as VariantArchiveResponse,
976
+ type VariantGetResponse as VariantGetResponse,
977
+ type VariantListResponsesCursorIDPage as VariantListResponsesCursorIDPage,
978
+ type VariantCreateParams as VariantCreateParams,
979
+ type VariantUpdateParams as VariantUpdateParams,
980
+ type VariantListParams as VariantListParams,
981
+ type VariantArchiveParams as VariantArchiveParams,
982
+ type VariantGetParams as VariantGetParams,
983
+ };
984
+ }